Modules

From Wiki
Jump to navigation Jump to search

Modules are extensions to ConTeXt’s core functions.

There are not as many modules for ConTeXt as packages for LaTeX, because ConTeXt’s core already contains a lot that needs a package in LaTeX.

Installation

Basics

The installation of extra files in TeX (called modules in ConTeXt) can be difficult for people who are new to TeX or are not themselves interested in TeX programming.

According to the TDS (TeX directory structure) and the ConTeXt developers, user-written files reside under the path

 $TEXMF/tex/context/third/<modulename>/<files>

In the private TeX directory ($TEXMF), directories can have the names

  • texmf-local
  • texmf-extra
  • texmf-project

but their existence depends on the TeX distribution; among these, texmf-local is the most common.

Installation by hand

When you want to install a new single-file module, create the subdirectories in the way described above and place the file there.

Most modules consist of several files though and are distributed as ZIP archives that contain the necessary TDS tree. These you can unzip in the top-level directory (e.g. texmf-local/), and all files should be in the correct place.

After the files are installed, you must update ConTeXt’s database to let it know where it can find the files:

 context --generate

(ConTeXt doesn’t use ls-R files or kpsewhich any more.)

Installation by script (LMTX)

Since 2023-05, there’s a script for mtxrun to list and install modules, usually from https://modules.contextgarden.net. Some modules, get special treatment: For the TikZ modules files are downloaded from CTAN and patches for incompatibilities are applied.

First, cd into the tex directory of your ConTeXt LMTX installation (above the texmf-* trees), the modules installer works only there.


 mtxrun --script install-modules --list

For the installation to work, you must change into the tex directory that contains the texmf-* trees.

 mtxrun --script install-modules --install filter simpleslides

If you list single modules to install, leave out the prefix (t-* or whatever)!

But since there aren’t many, you can just install all modules:

 mtxrun --script install-modules --install --all

Previously, the ConTeXt LMTX distribution did not provide a built-in way to install or update modules. Here’s a method using rsync, to be run from the toplevel directory of the ConTeXt LMTX distribution, i.e. the directory that contains install.sh.

Because the final tex/texmf-modules must contain the union of all individual module directories, the commands create and leave an intermediate modules directory that wastes less than 50 MB.

 # Synchronize all modules from ConTeXt Garden in the 'modules' directory, which is created if it doesn’t exist.
 
 rsync --recursive --links --times --info=progress2,remove,symsafe,flist,del --human-readable --del rsync://contextgarden.net/minimals/current/modules/ modules
 
 # Create the union of all modules in tex/texmf-modules (the directory is created if it doesn’t exist).
 # If you have personal modules in tex/texmf-modules, they won’t be modified.
 mkdir -p tex
 rsync -rlt --exclude=/VERSION --del modules/*/ tex/texmf-modules
 # You may delete the 'modules' directory to reclaim some space or keep it to speed up the next update.
 # rm -rf modules
 
 # Update the ConTeXt file database.
 mtxrun --generate


Installation by script (MkIV)

Users of the ConTeXt MkIV standalone can use the first-setup script to install modules:

E.g. to install the simpleslides modules:

 first-setup.sh --modules="t-simpleslides"

To install more modules at the same time:

 first-setup.sh --modules="t-simpleslides,t-french"

TeX Live

TeX Live is a large TeX distribution for most common operating systems. It provides binaries and many other files necessary to run TeX and its flavors. Many ConTeXt modules are included.


Usage

When you load a module with \usemodule[modulename] ConTeXt looks for a file with the following names:

  • m-modulename (core module)
  • p-modulename (private module)
  • s-modulename (ConTeXt style file)
  • x-modulename (XML module)
  • t-modulename ("third party" contributed module)
  • modulename

Once a file is found, ConTeXt stops the search and loads the found file (only once).

When you have two files with the same name but different prefixes, you can tell ConTeXt which file it should load with

\usemodule[<prefix>][modulename]

Included Modules

as of 2023-09-30

Macro modules


Style modules

in texmf-context/tex/context/modules/common:

  • s-cdr-00.tex: CD-ROM cover style
  • s-faq-00.tex to -03: FAQ styles
  • s-pre-00.tex to -96: Several old presentation styles (replaced by the following)

in texmf-context/tex/context/modules/mkiv:

  • s-present-*.tex: Several presentation styles (examples in texmf-context/doc/context/presentations/examples)

… many more …

Contributed Modules

For a list of contributed modules see the modules section on contextgarden.net:


Special Purpose Modules

The following modules implement special formatting requirement for journals or magazines. These modules are distributed with ConTeXt, so you need not download anything.

  • My Way, User documentation on ConTeXt
  • cgj Articles for ConTeXt Journal (proceedings of ConTeXt meetings)
  • pracjourn Articles for The PracTeX Journal
  • maps Articles for MAPS, the publication of NTG (Nederlandstalige TeX Gebruikersgroep or Netherlands TeX Group)

Module writing guidelines

Please don’t publish font support modules any more! They’re usually unnecessary. Instead publish typescripts in the wiki instead.

Module requirements

While a module usually consists of one main file with a name like t-modulename.[tex|ctx|mkiv|mkxl], there can be many more files, and there should be some documentation. Please adhere to the filename conventions outlined in [#Usage].

Sort these files into folders according to TDS (TeX directory structure) – just have a look at the distribution to understand what goes where.

  • Module code and data files go into tex/context/third/modulename
  • Documentation files go into doc/context/third/modulename
  • You can also look at properly setup git repositories like that of the simpleslides module.

Module release file

  • A release file is a ZIP archive that contains the necessary files in a TDS compliant structure.
  • The filename should be t-modulename-version.zip, where the version is usually a date like YYYY.MM.DD (but that’s up to you).
  • On the top level there must be a VERSION file that only contains your version string.
  • On the top level there should be a README(|.md|.txt) file with some metadata like a short description and author info.
  • On the top level there can be a LICENSE file containing the text of an open source license of your choice, if the license is not included in the README.
  • On the top level there must NOT be a folder with the module name, but only TDS folders like "doc" and "tex".

The same applies for git/SVN repositories containing ConTeXt modules.

VERSION and README files are important for publication on CTAN. README is also displayed on git platforms like GitHub or Codeberg and should contain basic documentation. All top level files are ignored by the LMTX module installer.

Instead of zip files, also tar.gz archives are possible, but the installer script can only handle zip – libzip is a necessary part of Lua(Meta)TeX, while other archive formats are not.

Module main file

All module files should start with a block containing meta information about that module. There is a Module template available to help setting up that header correctly.

License

Do not forget to specify a license as the permitted modes of distribution depend on which one you choose. The ConTeXt sources are licensed either under GPLv2 or the LPPL, so you might want to stick to these or a more permissive license. (Choose one: [1].) Including the full text of your license in your source repo is best practice.

In order to avoid conflicting macros it is essential for a module that it adheres to the namespace convention. After releasing a module its namespace[s] should be registered in the list for other module authors to know.

XML Interface file

Each module should have an associated XML specification file (as in /tex/context/interface/cont-en.xml). Its purpose is a comprehensive listing of the optional and non-optional arguments accepted by macros defined in the module.

From the interface a good deal of documentation can be auto-generated, as are for instance the ConTeXt Quick Reference and the initial input of the Command Reference, which itself started as a wikification of the now obsolete TeXshow.

When documenting your module, you can use

\usemodule[setups-basics]
\loadsetups[t-name-of-your-module.xml] % to load the file with definitions
\setup{nameofyourcommand}

An example:

\setuppapersize[A5]
\usemodule[setups-basics]
\loadsetups[i-framed]
\setup{setupframed}

By default, this places a frame around the setup. If you want to get gray background, as in the ConTeXt documentation, add a setup like:

 \setupframedtexts
     [setuptext]
     [background=color,
      backgroundcolor=lightgray,
      frame=off]

Apart from the existing XML files in the ConTeXt tree, there is little documentation online, so feel free to relay your questions to the mailing list.

Self-documenting source code

Source files are supposed to contain explanatory comments that document implementation details and other peculiarities the reader should be aware of.

In .tex files (and other files containing primarily TeX code, e.g. .mki[iv]) any line beginning with the comment leader %D will be treated as such a docstring. Formatting is done via ordinary TeX commands.

In Lua files (e.g. .cld) multi-line comments start with --[[ldx-- and end with --ldx]]--. Text inside those delimiters can be formatted using basic HTML tags. Ordinary comments are still treated as part of the source and therefore they will be typeset inside the listing.

Docstrings, though they appear to the [Lua]TeX interpreter as ordinary comments, allow for pretty printing source code when used with two dedicated modules:

Thus, in order to generate the documentation for the hypothetical simple module you first have to chdir to the files subdirectory of your checkout.

Next you run the pretty printer on its main file

context --ctx=s-mod t-simple.tex

to get a t-simple.pdf which contains the – sparse – annotations in serif and the actual code as colorful listing.

Likewise the processing of Lua code, e.g. font-def.lua from the main ConTeXt tree:

context --ctx=x-ldx font-def.lua

Which should generate a font-def.pdf in your current directory.

Publication and maintenance

  • Please upload your module(s) to https://modules.contextgarden.net! Our server scripts handle distribution for ConTeXt and CTAN.
  • Register an account, then you can login to the “member section”.
  • If you lost your password, please ask Taco or Mojca (via the mailing list if you don’t know them).
  • Please read the help page (it’s mostly the same as here).
  • Create a new module entry with a distinct name (e.g. “simple”; this will become the internal ID) and fill in the metadata:
    • Title, e.g. “Simple” (This will get used in filenames!)
    • Short and longer description (the short one gets published e.g. in CTAN updates).
    • Home URL, if the module has a homepage, e.g. a wiki page or git repository.
    • Keywords (for CTAN search)
    • Type: Macro or font (Please don’t publish font modules any more!)
    • Works with Mk... (please check)
    • License (there are licenses missing, we need to fix that)
    • Check “Put in download section” (yes please, allows installation by script)
    • Check “Put in ConTeXt distribution” (not sure if this works)
    • Check “Synch with CTAN” (yes please, makes it visible)
    • CTAN location: e.g. “/macros/context/contrib/context-simple
    • Comment: for you or the server admins
  • Create a new module version from a ZIP upload/download or checkout from SVN or git
    • Log message: short information about changes in this version
    • Version: usually YYYY.MM.DD, but up to you
    • File upload / HTTP download URL: release file as ZIP, as outlined above
    • SVN/GIT URL: repository checkout, structured like the ZIP, as outlined above

As an module author, it makes sense to subscribe to the developers mailing list.