ConTeXt and Lua programming/Module writing

Unofficial ConTeXt Wiki mirror

Last modified: 2025-01-18

< Modules

Introduction

When and for what should you write a public module?

What to aim for:

What to avoid:

Please don’t publish support modules for text fonts any more! They’re usually unnecessary. Instead publish typescripts in the wiki instead. Support for symbols or unusual scripts might make sense.

Basics

Directory structure

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.

Sort these files into folders according to TDS (TeX directory structure):

Maybe also have a look at the distribution to understand what goes where.

There can be more top level files that might be useful for publication on CTAN, e.g. preview images.

Don’t publish unnecessary files! i.e. leave out everything that gets automatically created (e.g. *.log, *.tuc, *.tuo, m_k_i_v_*), backups (e.g. *.bak, *.sav) or that is only relevant to other programs or the operating system (e.g. .DS_Store, __MACOSX, .thumbs). If you use git, you can list these in a .gitignore file.

Techniques

See e.g. Wolfgang’s presentation (PDF) at ConTeXt meeting 2024.

In order to avoid conflicting macros it is essential for a module that it adheres to the namespace convention. After releasing a module add it to the list in Modules for other module authors to know.

Module requirements

Module release file

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.

Documentation

README

A README(|.txt|.md) file makes sense in a public git repository and for publication on CTAN. It should contain:

Manual

If a simple example and the self-documenting source code isn’t enough to understand usage and options of your module, please include a manual (source and PDF). You can use the How to make a MyWay style.

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.

ConTeXt provides several variations of comments to automatically create PDF documentation, see below.

TeX files

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

 %D Use this comment type for examples and explanations
 %D of the module. Keep in mind that each comment block
 %D creates a local group when you change settings.

 %M Use this comment type to load additional modules
 %M (even the one you’re documenting at the moment)
 %M or make layout changes, because unlike the previous,
 %M type settings are global.

 %C Use this comment type for text which should remain
 %C commented in the output, e.g. license information.

 %S B
 %S This comment type is used when you add text which
 %S should ignored/skipped. It is necessary to use "B"
 %S at the first and "E" at the last line.
 %S E

The latter style is never used in the source code of ConTeXt.

Lua files

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.

Create the documentation

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 module’s code directory.

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.

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:

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.

Unfortunately, this is still not used by anything else than your own documentation, but e.g. ConTeXt support for editors that relies on interface files could be easily extended to module interfaces.

Publication and maintenance

Beware, Taco is planning to rewrite the module website ATM (2024-10), this information might be slightly outdated.

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