%\usemodule[cgj]
%\setvariables[CG-Journal][NOFColumns=1]
%\define[1]\Web{\goto{\emph{#1}}[url(https://#1)]}

\startArticle[
  Title={How to Write a Module},
  %SubTitle={},
  RunningTitle={how to write a module},
  Author={Hraban Ramm & Wolfgang Schuster},
  RunningAuthor={hraban ramm & wolfgang schuster},
  Email=,]

\startAbstract
Modules are reusable code and should adhere to the same conventions as \CONTEXT. How can you achieve all that fancy \tex{setup} and key-value parameter stuff?
\stopAbstract

\section{Introduction}

Hraban found his code too ugly and asked for a workshop to learn how to make it better. Wolfgang took pity and delivered.

While nothing stops you from writing modules for your own needs, this article is aimed at public modules. We’ll start with the \quote{philosophy}:

\subsection{When should you write a public module?}

A module is a collection of resuable code that is general enough that it may be of use for others, but complex enough that it’s more than a few settings.

\subsection{What to aim for}

Your module should follow common \CONTEXT\ practices, as far as it makes sense: \tex{define} an instance, \tex{setup} key-value parameters, provide a \tex{start} … \tex{stop} environment as well as a short \tex{command}.

Your code is only useful for others if it’s well documented and if you support it for at least a while – answer to questions, fix bugs, adapt it to new \CONTEXT\ versions and maybe enhance it.

\subsection{What to avoid}

Your module must not interfere with core features or commands. If there’s something in the distribution that you would like to fix, provide a fix and not a workaround module.

Usually it makes no sense to offer options for settings that are better handled by default setup commands. E.g. don’t offer a range of font presets instead of leaning on \tex{setupbodyfont}. Of course you’re welcome to suggest settings and to document limitations.

Don’t create modules for just a few settings – that might make sense for private code (environment or module), but we don’t want to follow the \LaTeX\ fashion of micropackages that just exist because the settings are too obscure.

Avoid undocumented low level code, because it’s prone to change instead of high level commands that are usually stable.

Don’t publish modules if you don’t want to support them (or find someone else who’s interested in it and takes over).

Font support modules are usually unnecessary. Better publish a typescript on the wiki. Support for symbols or unusual scripts might make sense though.

\section{File naming conventions}

For compatibility (also with CTAN), use 7 bit ASCII file names with only one dot and no other interpunction than hyphens (don’t use underscores).

You need a \quotation{code word} as module ID. Choose a short and unique name that hints at the function or is at least original. Avoid naming conflicts with core files and other modules. In our examples, this will be \quotation{messenger}.

Usually, a module has one \quotation{entry point} or \quotation{main file} that is loaded with \tex{usemodule}. This file starts with a code letter:

\startitemize[packed,joinedup]
\startitem \type{m}: core module – not for you\stopitem
\startitem \type{p}: private code – unpublished, use at will\stopitem
\startitem \type{s}: style – an environment that is to be used unchanged\stopitem
\startitem \type{x}: xml – support for one flavour of XML\stopitem
\startitem \type{t}: third party – usually what you would publish\stopitem
\stopitemize

File extensions for the module file can be:
\startitemize[packed,joinedup]
\startitem \type{.tex}: generally usable\stopitem
\startitem \type{.cld}: \CONTEXT\ Lua document, if it’s \CONTEXT-style Lua code\stopitem
\startitem \type{.lua}: general Lua code\stopitem
\startitem \type{.mkiv}, \type{.mkxl}: if you want to distinguish code for MkIV and LMTX\stopitem
\startitem \type{.mkvi}, \type{.mklx}: MkIV / LMTX with named macro parameters\stopitem
%\startitem \type{.mkix}: file with lmx template\stopitem
%\startitem \type{.mkxi}: file with lmx template with named parameters\stopitem
\stopitemize

Of course you can use other file extension for additional files.

Our example module file is named \filename{t-messenger.tex}.

\section{Directory structure}

It makes sense to keep your module in a version control system such as Git, Subversion or Mercurial. We’ll refer to Git, since it’s the most common one.

The same rules apply to a Git repository or a ZIP file, their folder structure is defined by TDS (\TeX\ directory structure).

The following \bold{top level files} are required for publication and get deleted or moved to \type{doc} on installation:

\startitemize[packed,joinedup]
\startitem \filename{README}(\type{|.txt|.md}): a simple text or Markdown file, \quotation{homepage} text of a public git repository (see below) and on CTAN\stopitem
\startitem \filename{VERSION}: contains only the version date, preferably as a date like \type{2024.04.01}\stopitem
\startitem \filename{LICENSE}: license text (plain text)\stopitem
\stopitemize

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

\startitemize
\startitem Your \bold{code files}, i.e. everything that does the actual work of your module, belong in \filename{tex/context/third/}\emph{\type{modulename}}\footnote{The additional level \filename{tex/context/}\bold{\type{modules}}\type{/third/}\emph{\type{modulename}} would make sense, but since modules are usually installed in \filename{texmf-modules} and most existing modules omit the \filename{modules} folder, we’ll continue to omit it.}. Often this is only your one module file.\stopitem
\startitem \bold{Documentation} goes into \filename{doc/context/third/}\emph{\type{modulename}}.\stopitem
\startitem An \bold{interface} XML file would be nice, it belongs in \filename{tex/context/interface/third}.\stopitem
\startitem In case you provide \bold{scripts} that extend \type{mtxrun}, they belong in \filename{scripts/context/lua/third/}\emph{\type{modulename}}.\stopitem
\startitem If your module needs special \bold{fonts}, put them into \filename{fonts/data/}\emph{\type{modulename}}.\stopitem
\stopitemize

Don’t publish unnecessary files! Leave out everything that is created automatically (e.g. \type{.log}, \type{.tuc}, \type{m_k_i_v_*}), backups (\type{.bak}, \type{.sav} …) or anything that is only relevant to other programs or the operating system (\type{.DS_Store}, \type{.project} …). In Git, list these in a \filename{.gitignore} file.

\section{Licensing}

Even if you don’t care about what happens with your code, choose appropriate licenses for your code. (If you don’t define a license, everyone must assume standard copyright.)

The \ConTeXt\ sources are licensed under GPLv2 or the LPPL, so you might want to stick to these. \ConTeXt\ documentation is double-licensed under GNU FDL 1.3 and CC-BY-SA 3.0.

If you include files by others, check their license! Don’t include copyrighted material!

\section{Module template}

The following can be used as a template for the header and structure of a module (main file):

\startTEX[numbering=file]
%D \module
%D   [     file=<filename>, % e.g. t-messenger
%D      version=<module version>, % e.g. 2024.04.01
%D        title=<module title>, % e.g. \CONTEXT\ User Module
%D     subtitle=<module subtitle>, % short description
%D       author=<author>, % name(s)
%D        email=<author email>,
%D         date=<date>, % e.g. \currentdate
%D    copyright=<copyright>, % e.g. <author>
%D      license=<license>] % e.g. 'GNU GPL 2.0'

%C copyright/license information

% begin info
%
% title   : <a short title to explain the module>
% comment : <a longer description of the purpose of the module>
% status  : <current status of the module>
%
% end info

\unprotect

% module code

\protect

\continueifinputfile {<filename>}

% usage examples

\endinput
\stopTEX

\subsection{Preamble}

The entries \type{type}, \type{subtitle}, and \type{author} are mandatory and get used for the title page of the code documentation (\in{}[sec:rundocs]).

The entries \type{file}, \type{version}, \type{copyright}, \type{license}, and \type{email} are optional.

\subsection{Info block}

In addition to the preamble it’s suggested to add an information block which gives a short description about the module and its status. It is used with \type{context --showmodules}.

\subsection{Examples}

Besides using the documentation mechanism and creating a separate document to explain the module, it is possible to add code at the end of the file after \tex{continueifinputfile} which is ignored when the module is loaded with \tex{usemodule}.

The argument of \tex{continueifinputfile} takes the filename of the module. Content after that is processed when you process the module itself  (\in{}[sec:rundocs]).

\subsection{Private area}

To ensure that the module can’t be changed by users and to enable the multilingual interface, \ConTeXt\ permits special characters in command names between \tex{unprotect} and \tex{protect} (\in{}[sec:namespace]).

Between these commands, you can use ?, !, @ and _ as part of command names, e.g.

\startTEX
\messenger_start
\????messenger
\c!location
\stopTEX

\section[sec:namespace]{Namespace and setups}

\subsection{Rise of the command handler}

In ye olden MkII tymes and early MkIV days\footnote{… when small furry creatures from Alpha Centauri were real small furry creatures from Alpha Centauri.}, all \tex{define} and \tex{setup} commands had to be written manually:

\startTEX
\def\definemessenger
  {\dotripleempty\dodefinemessenger}

\def\dodefinemessenger[#1][#2][#3]%
  {...}

\def\setupmessenger
  {\dodoubleempty\dosetupmessenger}

\def\dosetupmessenger[#1][#2]%
  {...}
\stopTEX

If you change the parameters of a command or environment with a \tex{setup} command, the value has to be stored in a macro.

The setting
\startTEX
\setupmessenger[width=10cm]
\stopTEX
was achieved with
\startTEX
\getparameters[messenger][width=10cm]
\stopTEX
which resulted in the internal representation
\startTEX
\def\messengerwidth{10cm}
\stopTEX

To make it easier to create these commands, to keep names unique and to ensure that macros are protected from user changes, namespaces and a mechanism called \quote{command handler} were added to \CONTEXT\footnote{… by the Great Old Ones, when the stars were right, of course.}.

\subsection{Namespaces}

You can use \tex{installnamespace}\arg{…} to create one or more namespaces for a module.

When you use this to create a \emph{messenger} namespace, you get a protected macro \tex{????messenger} to use in the upcoming definitions.

If you expand this macro, you get something like \tex{2DD>}, which cannot be used in normal documents.

When we replace the previous assignment with
\startTEX
\getparameters[\????messenger][width=10cm]
\stopTEX
we now get the internal representation
\startTEX
\def\2DD>width{10cm}
\stopTEX

\subsection{\tex{define} handler}

The first step to create a new command or environment is to create a \tex{define} command. (This doesn’t make sense for every kind of command/environment.)

\startTEX
\installdefinehandler \????COMMAND {COMMAND} \????COMMAND
\stopTEX
creates \tex{defineCOMMAND}\type{[instance][parent][key=value‚]} which has two optional arguments that can be used to create a new instance or make a copy of an existing instance and set the default values for that new instance.

The names of the instance and its parent can be accessed with \tex{currentCOMMAND} and \tex{currentCOMMANDparent}.

\subsubsection{Define hooks}

You can setup settings on definition of a new instance using \tex{everypresetCOMMAND} and \tex{everydefineCOMMAND}.

Before \CONTEXT\ reads the list of instance specific settings (\tex{defineCOMMAND}\type{[…][key=value]}) on instanciation, it executes \tex{everypresetCOMMAND}. This is useful e.g. to reset a counter.

\tex{everydefineCOMMAND} is executed after that. You can now check the values and decide what to do with them. This is also used to create new commands (e.g. \tex{footnote}) for the document.

\subsubsection{Example}

We create a \emph{messenger} environment and want different instances for different messengers.

\startTEX
\installnamespace {messenger}
\installdefinehandler \????messenger {messenger} \????messenger
\definemessenger[signal][width=17dk]
\stopTEX

Now we have the command \tex{definemessenger}\type{[…][…][…=…‚]} that inherits settings from \tex{setupmessenger}. We have defined \emph{signal} as an instance of \emph{messenger}, but that doesn’t work automagically. You must employ the \tex{everydefinemessenger} hook, so that a custom environment is created when you call \tex{definemessenger}:

\startTEX
\appendtoks
  \setevalue{\e!start\currentmessenger}{\messenger_start{\currentmessenger}}%
  \setevalue{\e!stop \currentmessenger}{\messenger_stop }%
\to \everydefinemessenger
\stopTEX

To reset a counter before instanciation, as mentioned above:

\startTEX
\appendtoks
  \resetmessengerparameter\s!counter
\to \everypresetmessenger
\stopTEX

% don’t know…

% \startTEX
% \appendtoks
%   \ifempty{\messengerparameter\s!counter}%
%     \letmessengerparameter\s!counter\currentmessenger
%     % create new counter
%     \normalexpanded{\definecounter[\messengerparameter\s!counter]}%
%   \fi
% \to \everydefinemessenger
%
% \appendtoks
%   % create a command that increments and outputs the counter
%   \edefcsname\currentmessenger\endcsname{\incrementedcounter[\messengerparameter\s!counter]}%
% \to \everydefinemessenger
% \stopTEX

\subsection{\tex{setup} handler}

The next step is a \tex{setup} command to set and change values.

\tex{installsetuphandler}\type{\????COMMAND {COMMAND}} creates \tex{setupCOMMAND}\type{[…][…=…‚]} with one optional argument to indicate the instance.

Additionally, you get \tex{setupcurrentCOMMAND}\type{[…=…‚]} to change a value within a command or environment.

The name of the current instance is again accessible as \tex{currentCOMMAND}.
Additional settings can be applied with \tex{everysetupCOMMAND} and \tex{everysetupCOMMANDroot}.

\quote{Root} means the base instance, without using \tex{define}; in our example it’s \emph{messenger}. If you use \tex{setup} without mentioning an instance name, the settings are valid for all instances.

\subsubsection{Example}

We want to assign default values to the \emph{messenger} environment and let users change them.

\startTEX
\installsetuphandler \????messenger {messenger}
\setupmessenger[width=99ts]
\setupmessenger[signal][width=17dk]
\stopTEX

Now we have our \tex{setupmessenger}\type{[…][…=…‚]} command and also a local \tex{setupcurrentmessenger}\type{[…=…‚]} command.

\subsection{Parameter handlers}

The last step is to provide a way to access the values of the \tex{setup} command.

\startTEX
\installparameterhandler \????COMMAND {COMMAND}
\stopTEX
creates:
\startitemize[packed,joinedup]
\startitem\tex{currentCOMMAND} (as before)\stopitem
\startitem\tex{COMMANDparameter}\arg{key}\stopitem
\startitem\tex{namedCOMMANDparameter}\arg{instance}\arg{key}\stopitem
\startitem\tex{detokenizedCOMMANDparameter}\arg{key}\stopitem
\startitem\tex{directCOMMANDparameter}\arg{key}\stopitem
\startitem\tex{letfromCOMMANDparameter}\type{\… {…}}\stopitem
\stopitemize

\subsubsection{Example}

Finally we want to access the values of the \emph{messenger} environment:

\startTEX
\installparameterhandler \????messenger {messenger}

\messengerparameter{width}
\namedmessengerparameter{signal}{width}
% etc.
\stopTEX

\subsubsection{Root parameter handler}

In case we want to access the root values of a command, we can create additional handlers:

\startTEX
\installrootparameterhandler \????COMMAND {COMMAND}
\stopTEX
creates \tex{detokenizedrootCOMMANDparameter}\arg{…} and \tex{rootCOMMANDparameter}\arg{…}.

If you use \tex{COMMANDparameter}, it checks if there is a instance specific value, if not, you’ll get the root value. With \tex{rootCOMMANDparameter}, you’ll directly get the root value, while with \tex{directCOMMANDparameter} you’ll get instance values without fallback.

If you set \tex{currentCOMMAND} to \type{empty}, all three \type{parameter} commands will give you root values.

\subsection{Style and color handler}

For many commands and environments, styling by the usual \type{style} and \type{color} keys makes sense.

After we have established a way to create new commands and environments as well as set and access their parameters, we still lack a way to apply these settings.

\startTEX
\installstyleandcolorhandler \????COMMAND {COMMAND}
\stopTEX
creates
\startitemize[packed,joinedup]
\startitem\tex{COMMANDparameter}\arg{…} \stopitem
\startitem\tex{useCOMMANDstyleandcolor}\arg{…}\arg{…} \stopitem
\startitem\tex{useCOMMANDstyleparameter}\arg{…} \stopitem
\startitem\tex{useCOMMANDcolorparameter}\arg{…} \stopitem
\stopitemize

\subsubsection{Example}

We can now use the style and color mechanism with \emph{messenger} setups.

\startTEX
\installstyleandcolorhandler \????messenger {messenger}
\usemessengerstyleandcolor {style} {color}
\usemessengerstyleparameter {style}
\usemessengercolorparameter {color}
\stopTEX

\subsubsection{Parameter names}

Usual behavior for the \type{style} and \type{color} parameters is to affect the (main) text in your command or environment, but you’re not limited to those. Every key that you use with one of the \tex{use} commands above will understand the usual styling shortcuts.

So it’s up to you which parameters you use for styling, but try to stay close to \CONTEXT’s conventions.

\startTEX
\setupmessenger[
  style={\ss\tfx},
  titlestyle=bold,
  titlecolor=orange,
  framecolor=white,
]
{\usemessengerstyleandcolor{style}{color}
styled text}
\framed[
  style=\usemessengerstyleparameter{style},
  color=\usemessengercolorparameter{color},
  framecolor=\usemessengercolorparameter{framecolor},
]{
{\usemessengerstyleandcolor{titlestyle}{titlecolor}my styled title}\par

other styled text
}
\stopTEX


\subsection{Parameter set handler}

In some cases you want to change the values of a single key.

\startTEX
\installparametersethandler \????COMMAND {COMMAND}
\stopTEX
creates:
\startitemize[packed,joinedup]
\startitem\tex{currentCOMMAND} (as before)\stopitem
\startitem\tex{setCOMMANDparameter}\arg{key}\stopitem
\startitem\tex{setexpandedCOMMANDparameter}\arg{instance}\arg{key}\stopitem
\startitem\tex{letCOMMANDparameter}\arg{key}\type{\…}\stopitem
\startitem\tex{resetCOMMANDparameter}\arg{key}\stopitem
\stopitemize

\subsubsection{Example}

We want a direct way to change \emph{messenger} values.

\startTEX
\installparametersethandler \????messenger {messenger}
\setmessengerparameter {key} {content}
\letmessengerparameter {ley} \…
\resetmessengerparameter {key}
\stopTEX
% HR: examples?

\subsection{Inherit from \tex{framed}}

As many features of \CONTEXT\ are based on \tex{framed}, we often want to use it for our own commands and environments.

\startTEX
\installinheritedframed {COMMAND}
\stopTEX
creates:
\startitemize[packed,joinedup]
\startitem\tex{currentCOMMAND} (as before)\stopitem
\startitem\tex{COMMANDparameter}\arg{key}\stopitem
\startitem\tex{COMMANDparameterhash}\arg{key}\stopitem
\startitem\tex{setupcurrentCOMMAND}\type{[key=value,]}\stopitem
\startitem\tex{inheritedCOMMANDframed}\arg{key}\stopitem
\startitem\tex{inheritedCOMMANDframedbox}\arg{key} \type{content}\stopitem
\stopitemize

\subsubsection{Example}

We want a new \tex{framed} command which takes its values from \tex{setupmessenger}.

To avoid clashes with other \emph{messenger} settings, the namespace and command name should be different from the default one.

\startTEX
\installnamespace {messengerframe}
\installinheritedframed \????messengerframe {messengerframe}
\stopTEX

This creates \tex{inheritedmessengerframeframed}\arg{content}, which is \tex{framed} with custom settings.

\subsection{Basic parameter handler}

To ease the creation of a new command or environment, \CONTEXT\ combines multiple handlers into a single \tex{install…handler} command.

The first one is
\startTEX
\installbasicparameterhandler \????COMMAND {COMMAND}
\stopTEX
which combines all commands for parameter access:

\startitemize[packed,joinedup]
\startitem\tex{installparameterhandler}\stopitem
\startitem\tex{installparameterhashhandler}\stopitem
\startitem\tex{installparametersethandler}\stopitem
\startitem\tex{installrootparameterhandler}\stopitem
\stopitemize

\subsection{Command handler}

The main handler used by most commands is
\startTEX
\installcommandhandler \????COMMAND {COMMAND} \????COMMAND
\stopTEX
which allows the creation of new commands, changing values and access to all values.

\startitemize[packed,joinedup]
\startitem\tex{installbasicparameterhandler}\stopitem
\startitem\tex{installdefinehandler}\stopitem
\startitem\tex{installsetuphandler}\stopitem
\startitem\tex{installstyleandcolorhandler}\stopitem
\stopitemize

\subsubsection{Namespace inheritance}

In most cases, you’ll use the same namespace for the first and third argument of \tex{installcommandhandler}, but you can also create an inheritance relation.

In the example below, \quote{TWO} inherits from \quote{ONE}, i.e. \tex{setupTWO} affects only \quote{TWO}, while it gets root settings from \tex{setupONE}.

\startTEX
\installnamespace {one}
\installnamespace {two}

\installcommandhandler \????one {ONE} \????one
\installcommandhandler \????two {TWO} \????one
\stopTEX

\subsection{Simple command handler}

For simpler commands without dedicated instances you can use
\startTEX
\installsimplecommandhandler \????COMMAND {COMMAND} \????COMMAND
\stopTEX
which lacks the \tex{define} handler.

\startitemize[packed,joinedup]
\startitem\tex{installbasicparameterhandler}\stopitem
\startitem\tex{installsetuphandler}\stopitem
\startitem\tex{installstyleandcolorhandler}\stopitem
\stopitemize

\subsection{Framed command handler}

The last major handler is
\startTEX
\installframedcommandhandler \????COMMAND {COMMAND} \????COMMAND
\stopTEX
which combines \tex{installcommandhandler} with the \tex{framed} handler.

\startitemize[packed,joinedup]
\startitem\tex{installcommandhandler}\stopitem
\startitem\tex{installinheritedframed}\stopitem
\stopitemize

\subsection{Local variables}

In some cases you want a mechanism to accept values as assignments which are local to the command or environment. This can be done with the predefined \tex{getdummyparameters}.

\startTEX
\getdummyparameters[key=value]
\dummyparameter{key}
\stopTEX

\subsubsection{Example}

\startTEX
\def\messagetext[#1]{#2}%
 {\begingroup
  \getdummyparameters[sender=,#1]%
  \dummyparameter{sender}: #2%
  \endgroup}
\stopTEX

\section{Complete example}

\startTEX[numbering=file]
%D \module
%D   [     file=t-messenger,
%D        title=\CONTEXT\ user module,
%D     subtitle=Messenger dummy,
%D      version=2024.08.20,
%D       author=Wolfgang Schuster,
%D    copyright=Wolfgang Schuster,
%D      license=Public Domain,
%D        email=wolfgang.schuster.lists@gmail.com]

\unprotect

\installnamespace {messenger}
\installnamespace {messengerchat}
\installnamespace {messengerframe}

\installcommandhandler       \????messenger      {messenger}      \????messenger
\installcommandhandler       \????messengerchat  {messengerchat}  \????messengerchat
\installframedcommandhandler \????messengerframe {messengerframe} \????messengerframe

\appendtoks
    \edefcsname\e!start\currentmessenger\endcsname{\startmessenger[\currentmessenger]}%
    \edefcsname\e!stop \currentmessenger\endcsname{\stopmessenger                    }%
\to \everydefinemessenger

\appendtoks
    \normalexpanded{\definemessengerframe[\currentmessengerchat]}%
\to \everydefinemessengerchat

\newtoks\t_messenger

\tolerant\protected\def\startmessenger[#1]#*[#2]%
  {\begingroup
   \cdef\currentmessenger{#1}%
   \ifparameter#2\or
     \setupcurrentmessenger[#2]%
   \fi
   \expand\t_messenger
   \usemessengerstyleandcolor\c!style\c!color}

\protected\def\stopmessenger
  {\endgroup}

\lettonothing\m_messengerchat_previous

\tolerant\protected\def\messenger_chat[#1]#:#2%
  {\par
   \begingroup
   \cdef\currentmessengerchat {#1}%
   \cdef\currentmessengerframe{#1}%
   \ifx\m_messengerchat_previous\currentmessengerchat \else
     % person has changed!
   \fi
   \ifcstok{\messengerchatparameter\c!location}\v!left
     \leftaligned {\inheritedmessengerframeframed{#2}}%
   \else
     \rightaligned{\inheritedmessengerframeframed{#2}}%
   \fi
   \globallet\m_messengerchat_previous\currentmessengerchat
   \endgroup}

\appendtoks
    \let\chat\messenger_chat
\to \t_messenger

\protect

\continueifinputfile{t-messenger.mkxl}

\starttext

\usemodule[visual]

\definemessenger[signal]

\definemessengerchat [a] [location=left]
\definemessengerchat [b] [location=right]

\setupmessengerframe [width=.7tw,autowidth=force,align=yes]

\setupmessengerframe [a] [framecolor=red]
\setupmessengerframe [b] [framecolor=green]

\startsignal
\chat[a]{\fakewords{3}{8}}
\chat[b]{\fakewords{3}{8}}
\chat[a]{\fakewords{3}{8}}
\chat[b]{\fakewords{3}{8}}
\chat[b]{\fakewords{3}{8}}
\stopsignal

\stoptext
\stopTEX


\section{Documentation}

\subsection[sec:readme]{README}

A \filename{README} file (usually plain text or Markdown) makes sense in a public git repository and for publication on CTAN. It should contain:

\startitemize[packed,joinedup]
\startitem title of the module\stopitem
\startitem a short explanation what it does\stopitem
\startitem dependencies (\ConTeXt\ LMTX, fonts, other programs)\stopitem
\startitem a hint on installing (e.g. via \type{mtxrun})\stopitem
\startitem an example of its use\stopitem
\startitem references to further documentation\stopitem
\startitem the list of authors/contributors\stopitem
\startitem license (name and link to the \filename{LICENSE} file)\stopitem
\stopitemize

\subsection{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 MyWay style.

\subsection[sec:selfdocumenting]{Self-documenting sourcecode}

\subsubsection{\TeX\ files}

In \type{.tex} files (and other files containing primarily \TeX\ code, e.g. \type{.mkiv}), any line beginning with a comment leader will be treated as a \quote{docstring}. Formatting is done via ordinary \CONTEXT\ commands.

\startTEX
%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.
\stopTEX

\startTEX
%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.
\stopTEX

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

\startTEX
%S B
%S This comment type can be used to add text that should
%S be ignored/skipped. You must use "B" as the first
%S and "E" as the last line.
%S E
\stopTEX

The last version is nowhere used in \CONTEXT’s source code. We’re not sure when it would make sense.
\blank

Docstrings, though they appear to the \TeX\ interpreter as ordinary comments, allow for pretty printing source code.

In order to generate a PDF with source code as a colorful listing and the docstrings as plain serif text, run \type{context} on your main file like this:

\starttyping
context --extra=module --result=messenger t-messenger
\stoptyping

It is recommended to specify a filename for the resulting PDF file because the default is \filename{context-extra.pdf}.


\subsubsection{Lua files}

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

Also for Lua code there’s an option to create a PDF:

\starttyping
context --ctx=x-ldx font-def.lua
\stoptyping


\subsection{XML interface file}

Each module should have an associated XML specification file (as in \filename{/tex/context/interface/mkiv/i-*.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

\startTEX
\usemodule[setups-basics]
\loadsetups[t-messenger.xml] % to load the file with definitions
\setup{messenger}
\stopTEX

An example:

\usemodule[setups-basics]
\loadsetups[i-verbatim]
\setup{type}

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

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

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

\section{Publication and maintenance}

\emph{Beware,} Taco is re-writing the module website ATM (2024-09), this information might be slightly outdated.

Please upload your module(s) to \Web{modules.contextgarden.net}! Our server scripts handle distribution for \ConTeXt\ and CTAN.

\startitemize
\startitem Register an account, then you can login to the \quotation{member section}.\stopitem
\startitem If you lost your password, please ask Taco.\stopitem
\startitem Please read the help page (it’s mostly the same as this section).\stopitem
\startitem Create a \bold{new module} entry with a distinct name (e.g. \quotation{messenger}; this will become the internal ID) and fill in the metadata:
\startitemize[packed,joinedup]
\startitem Title (misleading, best use the same as before) \quotation{messenger} (This will get used in filenames!)\stopitem
\startitem Short and longer description (the short desc. is meant as the name and gets published e.g. in CTAN updates).\stopitem
\startitem Home URL, if the module has a homepage, e.g. a wiki page or git repository.\stopitem
\startitem Keywords (for CTAN search)\stopitem
\startitem Type: Macro or font (Please don’t publish font modules any more! Style, Lua and XML modules will get added soon.)\stopitem
\startitem Works with Mk... (please check)\stopitem
\startitem License (there are licenses missing, we need to fix that)\stopitem
\startitem Check \quotation{Put in download section} (yes please, allows installation by script)\stopitem
\startitem Check \quotation{Put in ConTeXt distribution} (ATM just a hint for the admins, no automation)\stopitem
\startitem Check \quotation{Synch with CTAN} (yes please, makes it visible; ATM just a hint for the admins)\stopitem
\startitem CTAN location: e.g. \filename{/macros/context/contrib/context-messenger}\stopitem
\startitem Comment: only for you and the server admins\stopitem
\stopitemize
\stopitem
\startitem Create a \bold{new module version} from a ZIP upload/download or checkout from SVN or git
\startitemize[packed,joinedup]
\startitem Log message: short information about changes in this version (if empty, latest commit message is used)\stopitem
\startitem Version: usually YYYY.MM.DD (hyphens are also ok; please avoid other versioning schemas)\stopitem
\startitem File upload / HTTP download URL: release file as ZIP, as outlined above\stopitem
\startitem SVN/GIT URL: repository checkout, structured like the ZIP, as outlined above\stopitem
%\startitem \stopitem
\stopitemize
\stopitem
\stopitemize

As a module author, it makes sense to subscribe to the developers mailing list\footnote{\Web{lists.contextgarden.net/mailman3/lists/dev-context.ntg.nl/}}.

\stopArticle
