Difference between revisions of "Modules"

From Wiki
Jump to navigation Jump to search
m (Added the t-markdown module.)
(23 intermediate revisions by 10 users not shown)
Line 1: Line 1:
< [[The ConTeXt Way]]
+
< [[The ConTeXt Way]]
  
 
Modules are extensions to ConTeXt's core functions.
 
Modules are extensions to ConTeXt's core functions.
Line 42: Line 42:
 
   context --generate
 
   context --generate
  
===ConTeXt minimals===
+
===ConTeXt standalone===
  
Users of the ConTeXt minimals dont't have to download the module files and unzip
+
Users of the ConTeXt standalone (formerly "minimals") distribution don't have to download the module files and unzip them in the local directory, because they can use the <tt>first-setup</tt> script for this.
them in the local directory because they can use the 'first-setup' for this.
 
  
 
To install for example the simpleslides modules you write
 
To install for example the simpleslides modules you write
  
   first-setup.sh --extras="t-simpleslides"
+
   first-setup.sh --modules="t-simpleslides"
  
 
To install more modules at the same time write
 
To install more modules at the same time write
  
   first-setup.sh --extras="t-simpleslides,t-french"
+
   first-setup.sh --modules="t-simpleslides,t-french"
  
The complete list of availables modules in minimals is:
+
The complete list of availables modules in standalone is:
  
* f-urwgaramond
+
* [http://modules.contextgarden.net/account t-account] draw T-accounts
* f-urwgothic
+
* [http://modules.contextgarden.net/algorithmic t-algorithmic] like LaTeX algorithmic
* t-account
+
* [http://modules.contextgarden.net/animation t-animation] create animations
* t-algorithmic
+
* [http://modules.contextgarden.net/annotation t-annotation] todo lists
* t-bib
+
* [http://modules.contextgarden.net/t-bnf t-bnf] BNF grammar
* t-bnf
+
* [http://modules.contextgarden.net/chromato t-chromato] chromatograms
* t-chromato
+
* [http://modules.contextgarden.net/cmscbf t-cmscbf] bold small caps
* t-cmscbf
+
* [http://modules.contextgarden.net/cmttbf t-cmttbf] bold typewriter
* t-cmttbf
+
* [http://modules.contextgarden.net/t-construction-plan t-construction-plan] figures with defined scale
* t-construction-plan
+
* [http://modules.contextgarden.net/t-degrade t-degrade] degrading JPEG images
* t-degrade
+
* [http://modules.contextgarden.net/fancybreak t-fancybreak] thought breaks
* t-fixme
+
* [http://modules.contextgarden.net/filter t-filter] run external programs on inline code
* t-french
+
* [http://modules.contextgarden.net/fixme t-fixme] like LaTeX fixme
* t-games
+
* [http://modules.contextgarden.net/t-french t-french]
* t-gnuplot
+
* [http://modules.contextgarden.net/fullpage t-fullpage]
* t-layout
+
* [http://modules.contextgarden.net/games t-games] board games
* t-letter
+
* [http://modules.contextgarden.net/gantt t-gantt] Gantt charts
* t-lettrine
+
* [http://modules.contextgarden.net/gnuplot t-gnuplot] include GNUplot graphics
* t-lilypond
+
* [http://modules.contextgarden.net/t-layout t-layout]
* t-mathsets
+
* [http://modules.contextgarden.net/letter t-letter] formal letters
* t-simplefonts
+
* [http://modules.contextgarden.net/t-lettrine t-lettrine] decorative paragraph starts (initials)
* t-simpleslides
+
* [http://modules.contextgarden.net/t-lilypond t-lilypond] include musical scores with GNU LilyPond
* t-taspresent
+
* [http://ctan.org/pkg/markdown t-markdown] render markdown documents
* t-tikz
+
* [http://modules.contextgarden.net/mathsets t-mathsets] mathematical sets, probabilities etc.
* t-typearea
+
* [http://modules.contextgarden.net/pararef t-pararef] {{cmd|startParagraph|link=no}}, for paragraphs as ‘thought blocks’ that may contain more than one 'TeX paragraph'. These paragraphs are numbered and can be referenced. See [[Paragraph Referencing]].
* t-typescripts
+
* t-pgfplots
* t-vim
+
* [http://modules.contextgarden.net/ruby t-ruby] Ruby markup (for Chinese, not programming language)
 +
* [http://modules.contextgarden.net/simplefonts t-simplefonts] simplified font mechanism
 +
* [http://modules.contextgarden.net/simpleslides t-simpleslides] presentations
 +
* [http://modules.contextgarden.net/typearea t-typearea] like LaTeX/KoMa typearea
 +
* [http://modules.contextgarden.net/typescripts t-typescripts] collection of typescripts
 +
* [http://modules.contextgarden.net/urwgaramond t-urwgaramond]
 +
* [http://modules.contextgarden.net/urwgothic t-urwgothic]
 +
* [http://modules.contextgarden.net/vim t-vim] syntax highlighting using vim’s syntax files
 +
 
 +
(some of these are obsolete...)
  
 
===TeX Live===
 
===TeX Live===
  
{{Note | description required}}
+
TeX Live is a large TeX distribution for most Linux and BSD based operating systems. It provides binaries and many other files necessary to run TeX and its flavors. Many ConTeXt modules are included.
  
 
The following modules are available:
 
The following modules are available:
Line 98: Line 106:
 
* context-french
 
* context-french
 
* context-games
 
* context-games
 +
* context-gantt
 
* context-gnuplot
 
* context-gnuplot
 
* context-letter
 
* context-letter
Line 125: Line 134:
 
<code>\usemodule[<prefix>][modulename]</code>  
 
<code>\usemodule[<prefix>][modulename]</code>  
  
==Included modules:==
+
==Included Modules==
* [[source:t-bib.tex|t-bib]]: [[Bibliography]] (maintained by Taco)
+
 
* [[source:m-arabtex.tex|m-arabtex]]: loading of Lagally's [[Arabian and Hebrew|ArabTeX]]
+
* {{code|bibl-bib.lua}} ({{src|bibl-bib.mkiv}}): [[Bibliography]] (maintained by Taco)
* [[source:m-chart.tex|m-chart]]: [[Flow Charts]]
+
* {{code|m-arabtex}} ({{src|m-arabtex.mkii}}): loading of Lagally's [[Arabian and Hebrew|ArabTeX]]
* [[source:m-chemic.tex|m-chemic]]: [[Chemistry|PPCHTeX]] (chemical structure formulae)
+
* {{code|m-barcodes}} ({{src|m-barcodes.mkiv}}): generate barcodes using PStricks. You should probably use m-zint instead.
* [[source:m-cweb.tex|m-cweb]]: [[CWEB]] pretty printing
+
* {{code|m-chart}} ({{src|m-chart.lua}} {{src|m-chart.mkii}} {{src|m-chart.mkvi}}): [[Flow Charts]]
* [[source:m-database.tex|m-database]]: creating simple tables (or forwarding data to user-defined commands) using [[m-database|comma/space/tab-separated values]]
+
* {{code|m-chemic}} ({{src|m-chemic.mkii}} {{src|m-chemic.mkiv}}): [[Chemistry|PPCHTeX]] (chemical structure formulae)  
* [[source:m-dratex|m-dratex]]: loading of DraTeX
+
* {{code|m-cweb}} ({{src|m-cweb.tex}}): [[CWEB]] pretty printing
* [[source:m-edtsnc.tex|m-edtsnc]]: support for editor synchronization, will replace m-pdfsync
+
* {{code|m-database}} ({{src|m-database.lua}} {{src|m-database.mkii}} {{src|m-database.mkiv}}): creating simple tables (or forwarding data to user-defined commands) using [[m-database|comma/space/tab-separated values]]. Wiki: [[M-database]].
* [[source:m-educat.tex|m-educat]]: educational additions (for settings school tests or questionaires)
+
* {{code|m-datastrc}} ({{src|m-datastrc.tex}}):
* [[source:m-gamma.tex|m-gamma]]: [[Aleph|Omega]] support
+
* {{code|m-directives}} ({{src|m-directives.mkiv}}):
* [[source:m-graph.tex|m-graph]]: support for [[MetaPost]] graph module
+
* {{code|m-dratex}} ({{src|m-dratex.mkii}}): loading of DraTeX
* [[source:m-layout.tex|m-layout]]: defines some [[Layout]] presets
+
* {{code|m-edtsnc}} ({{src|m-edtsnc.mkii}}): support for editor synchronization, will replace m-pdfsync
* [[source:m-level.tex|m-level]]: module for catching nesting errors
+
* {{code|m-educat}} ({{src|m-educat.tex}}): educational additions (for settings school tests or questionaires)
* [[source:m-narrowtt.tex|m-narrowtt]]: using a narrower [[Latin Modern]] font for verbatim
+
* {{code|m-fields}} ({{src|m-fields.mkiv}}):
* [[source:m-newmat.tex|m-newmat]]: support for some AMSmath features, is loaded by [[Math with amsl|amsl]], see [[Math with newmat]]
+
* {{code|m-format}} ({{src|m-format.tex}}):
* [[source:m-pdfsnc.tex|m-pdfsnc]]: editor/PDF synchronization support (used by iTeXMac and TeXShop)
+
* <strike>[[source:m-gamma.tex|m-gamma]]: [[Aleph|Omega]] support</strike>
* [[source:m-pictex.tex|m-pictex]]: needed for [[PicTeX]] without eTeX
+
* {{code|m-graph}} ({{src|m-graph.mkii}} {{src|m-graph.mkiv}}): support for [[MetaPost]] graph module
* [[source:m-plus.tex|m-plus]]: loads some extra features (currently empty)
+
* {{code|m-ipsum}} ({{src|m-ipsum.mkiv}}): lorem ipsum filler text
* [[source:m-pstric.tex|m-pstric]]: connection macros for [[PSTricks]] (PostScript tricks)
+
* {{code|m-layout}} ({{src|m-layout.tex}}): defines some [[Layout]] presets
* [[source:m-r.tex|m-r]]: typing and executing [http://www.r-project.org/ R] scripts
+
* {{code|m-level}} ({{src|m-level.mkii}}): module for catching nesting errors
* [[source:m-quest.tex|m-quest]]: module for fill-in forms (dutch only)
+
* {{code|m-logcategories}} ({{src|m-logcategories.mkiv}}):
* [[source:m-steps.tex|m-steps]]: Step Charts, see [[XML]] step charts
+
* {{code|m-markdown}} ({{src|m-markdown.lua}} {{src|m-markdown.mkiv}}):
* [[source:m-streams.tex|m-streams]]: Synchronised typesetting from different sources
+
* {{code|m-mathcrap}} ({{src|m-mathcrap.mkiv}}):
* [[source:m-subsub.tex|m-subsub]]: Defines 5 extra sectioning levels
+
* {{code|m-mkii}} ({{src|m-mkii.mkiv}}):
* [[source:m-tex4ht.tex|m-tex4ht]]: convert a ConTeXt document to html, more about it on [[tex4ht]]
+
* {{code|m-mkivhacks}} ({{src|m-mkivhacks.mkiv}}):
* [[source:m-tryout.tex|m-tryout]]: Contains temporary functions for testing
+
* {{code|m-morse}} ({{src|m-morse.mkvi}}):
* [[source:m-units.tex|m-units]]: Structured input of values with [[units]]
+
* {{code|m-narrowtt}} ({{src|m-narrowtt.tex}}): using a narrower [[Latin Modern]] font for verbatim
* [[source:m-visual.tex|m-visual]]: [[Visual Debugging]] (described in [[This Way]] no.7 [[manual:mag-0007.pdf|Faking Text and More]])
+
* {{code|m-newmat}} ({{src|m-newmat.tex}}): support for some AMSmath features, is loaded by [[Math with amsl|amsl]], see [[Math with newmat]]
 +
* {{code|m-ntb-to-xtb}} ({{src|m-ntb-to-xtb.mkiv}}):
 +
* {{code|m-obsolete}} ({{src|m-obsolete.mkii}} {{src|m-obsolete.mkiv}}):
 +
* {{code|m-oldfun}} ({{src|m-oldfun.mkiv}}):
 +
* {{code|m-oldnum}} ({{src|m-oldnum.mkiv}}):
 +
* {{code|m-pdfsnc}} ({{src|m-pdfsnc.mkii}}): editor/PDF synchronization support (used by iTeXMac and TeXShop)
 +
* {{code|m-pictex}} ({{src|m-pictex.tex}}): needed for [[PicTeX]] without eTeX
 +
* <strike>[[source:m-plus.tex|m-plus]]: loads some extra features (currently empty)</strike>
 +
* {{code|m-pstricks}} ({{src|m-pstricks.lua}} {{src|m-pstricks.mkii}} {{src|m-pstricks.mkiv}}):
 +
* {{code|m-punk}} ({{src|m-punk.mkiv}}):
 +
* <strike>[[source:m-quest.tex|m-quest]]: module for fill-in forms
 +
* (dutch only)</strike>
 +
* {{code|m-r}} ({{src|m-r.tex}}): typing and executing [http://www.r-project.org/ R] scripts
 +
* {{code|m-spreadsheet}} ({{src|m-spreadsheet.lua}} {{src|m-spreadsheet.mkiv}}):
 +
* {{code|m-steps}} ({{src|m-steps.lua}} {{src|m-steps.mkii}} {{src|m-steps.mkvi}}): Step Charts, see [[XML]] step charts
 +
* {{code|m-streams}} ({{src|m-streams.tex}}): Synchronised typesetting from different sources
 +
* {{code|m-subsub}} ({{src|m-subsub.tex}}): Defines 5 extra sectioning levels
 +
* {{code|m-tex4ht}} ({{src|m-tex4ht.mkii}}): convert a ConTeXt document to html, more about it on [[tex4ht]]
 +
* {{code|m-timing}} ({{src|m-timing.mkiv}}):
 +
* {{code|m-trackers}} ({{src|m-trackers.mkiv}}):
 +
* {{code|m-translate}} ({{src|m-translate.mkiv}}):
 +
* {{code|m-units}} ({{src|m-units.mkii}} {{src|m-units.mkiv}}): Structured input of values with [[units]]
 +
* {{code|m-visual}} ({{src|m-visual.mkii}} {{src|m-visual.mkiv}}): [[Visual Debugging]] (described in [[This Way]] no.7 [[magazine:0007|Faking Text and More]])
 +
* {{code|m-zint}} ({{src|m-zint.mkiv}}): Generate barcodes using [http://www.zint.org.uk zint.exe]
  
==Contributed modules:==
+
==Contributed Modules==
For a list of contributed modules see [http://modules.contextgarden.net the modules section] on contextgarden.net.
+
For a list of contributed modules see [http://tlcontrib.metatex.org/ tlcontrib] and/or [http://modules.contextgarden.net the modules section] on contextgarden.net.
  
 
{{todo|list more modules or none of them}}
 
{{todo|list more modules or none of them}}
Line 178: Line 210:
 
==Modules writing guidelines==
 
==Modules writing guidelines==
  
Prior to release 2005.05.25, ConTeXt silently truncated all file names in <cmd>usemodule</cmd> commands to 8 characters long and lowercased them to "prevent cross platform problems with filenames". Thus, module files that are to be used with older versions of ConTeXt must have filenames that fit those restrictions, or they will (somewhat cryptically) not be found.
+
===Module requirements===
 +
All modules should start with a block containing ''meta information'' about that module.
 +
There is a [[module template]] available to help setting up that header correctly.
  
All modules should start with a block containing meta information about that module. There is a
+
Do not forget to specify a ''license'' as the permitted modes of distribution
[[module template]] available to help setting that up correctly.
+
depend on which one you choose.
 +
The [http://wiki.contextgarden.net/Read_Me#The_Code 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: [http://www.opensource.org/].)
 +
Including the full text of your license in your source repo is best practice.
  
<b>TODO</b>
+
In order to avoid ''conflicting macros'' it is essential for a module that it adhere
 +
to the [[Module_Namespaces|namespace convention]].
 +
After releasing a module its namespace[s] should be registered in the [[Module_Namespaces#List_of_Module_Namespaces|list]] for other module authors to know.
  
Each module should have an associated specification file (as in [http://source.contextgarden.net/tex/context/interface/cont-en.xml /tex/context/interface/cont-en.xml]). Probably one day this will become a part of [http://texshow.contextgarden.net/ texshow] and will also be easy-to-edit.
+
===XML Interface file===
 +
Each module should have an associated XML specification file
 +
(as in [http://source.contextgarden.net/tex/context/interface/cont-en.xml /tex/context/interface/cont-en.xml]).
 +
Its purpose is a comprehensive listing of the optional and non-optional
 +
arguments that a macro defined in the module accepts.
 +
From the interface a good deal of documentation can be auto-generated,
 +
as are for instance the [http://pragma-ade.com/general/qrcs/setup-en.pdf ConTeXt Quick Reference]
 +
and the initial input of the [http://wiki.contextgarden.net/Category:Reference/en Command Reference],
 +
which itself started as a wikification of the now obsolete ''TeXShow''.
  
 
When documenting your module, you can use
 
When documenting your module, you can use
Line 196: Line 245:
 
An example:
 
An example:
 
<context source="yes">
 
<context source="yes">
 +
\setuppapersize[A5]
 
\usemodule[int-load]
 
\usemodule[int-load]
 
\loadsetups
 
\loadsetups
Line 201: Line 251:
 
</context>
 
</context>
  
By default, this places a frame around the setup. If you want to get gray backgroud, as in context documentation, add the following
+
By default, this places a frame around the setup. If you want to get gray background, as in the context documentation, add the following
  
 
<texcode>
 
<texcode>
 
  \setupframedtexts
 
  \setupframedtexts
 
     [setuptext]
 
     [setuptext]
     [background=screen,
+
     [background=color,
 +
      backgroundcolor=lightgray,
 
       frame=off]
 
       frame=off]
 
</texcode>
 
</texcode>
 +
 +
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|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 <tt>.tex</tt> files (and other files containing primarily TeX code, e.g.
 +
<tt>.mki[iv]</tt>) any line beginning with the comment leader <tt>%D</tt>
 +
will be treated as such a docstring.
 +
Formatting is done via ordinary TeX commands.
 +
In Lua files (e.g. <tt>.cld</tt>) multi-line comments start with
 +
<tt>--[[ldx--</tt> and end with <tt>--ldx]]--</tt>.
 +
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:
 +
* [[source:x-ldx.ctx|<tt>x-ldx.ctx</tt>]] for Lua files, and
 +
* [[source:s-mod.ctx|<tt>s-mod.ctx</tt>]] for TeX files.
 +
Thus, in order to generate the documentation for the
 +
[https://bitbucket.org/wolfs/simplefonts/src ''simplefonts'']
 +
module you first have to chdir to the <tt>files</tt> subdirectory of
 +
your checkout.
 +
Next you run the pretty printer on its main file
 +
<pre>
 +
context --ctx=s-mod t-simplefonts.tex
 +
</pre>
 +
to get a <tt>t-simplefonts.pdf</tt> which contains the &ndash; sparse
 +
&ndash; annotations in serif and the actual code as colorful listing.
 +
Likewise the processing of Lua code, e.g. <tt>[[source:font-def.lua|font-def.lua]]</tt> from
 +
the main ConTeXt tree:
 +
<pre>
 +
context --ctx=x-ldx font-def.lua
 +
</pre>
 +
Which should generate a font-def.pdf in your current directory.
 +
 +
(The autogenerated documentation of all ConTeXt sources has been
 +
made available by Luigi at [http://foundry.supelec.fr/gf/project/modules/].
 +
Go there for examples of the output.)
 +
 +
===Legacy modules disclaimer===
 +
<!-- This info is obsolete, the section could be kicked out, doesn’t it? -->
 +
Prior to release ''2005.05.25'', ConTeXt silently truncated all file names in <cmd>usemodule</cmd> commands to 8 characters long and lowercased them to "prevent cross platform problems with filenames".  Thus, module files that are to be used with older versions of ConTeXt must have filenames that fit those restrictions, or they will (somewhat cryptically) not be found.

Revision as of 19:07, 4 June 2016

< The ConTeXt Way

Modules are extensions to ConTeXt's core functions.

There are not as many modules for ConTeXt as packages for LaTeX, because a lot of LaTeX package features are in ConTeXt's core.

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 module which is available as file only create the subdirectories in the way described above and place the file there, for modules which are available as zip files with precreated subdorectories you can unzip the archive in the top-level directory (e.g. texmf-local/) and all files are on the correct place.

After the files are placed at the right place you have to update TeX's database to let it know where it can find the files, this is done for MkII with

 mktexlsr (command name depends on the TeX distribution)

and for MkIV with

 context --generate

ConTeXt standalone

Users of the ConTeXt standalone (formerly "minimals") distribution don't have to download the module files and unzip them in the local directory, because they can use the first-setup script for this.

To install for example the simpleslides modules you write

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

To install more modules at the same time write

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

The complete list of availables modules in standalone is:

(some of these are obsolete...)

TeX Live

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

The following modules are available:

  • context-account
  • context-bnf
  • context-chromato
  • context-construction-plan
  • context-degrade
  • context-french
  • context-games
  • context-gantt
  • context-gnuplot
  • context-letter
  • context-lettrine
  • context-lilypond
  • context-mathsets
  • context-simpleslides
  • context-taspresent
  • context-typearea
  • context-vim

Usage

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

  • m-modulaname (core module)
  • p-modulename (private module)
  • s-modulename (ConTeXt style file)
  • x-modulename (XML module)
  • t-modulename (Third party module)
  • modulename

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

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

\usemodule[<prefix>][modulename]

Included Modules

Contributed Modules

For a list of contributed modules see tlcontrib and/or the modules section on contextgarden.net.


TODO: list more modules or none of them (See: To-Do List)


  • xdesc (extended description, e.g. for epigrams)
  • nath (natural math, see Math)
  • amsl (AMSmath, see Math)
  • Gnuplot: support for direct inclusion of Gnuplot graphs out of the source (the module has been removed from the main distribution and will be included into third party modules again when ready)

File names of included modules start with "m-", but third party (contributed) modules should start with "t-".

In order to install a contributed module, copy its directory into $TEXMF/tex/context/third then run luatools --generate.

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.

Modules writing guidelines

Module requirements

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

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 adhere 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 that a macro defined in the module accepts. 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[int-load] %Allow xml parsing 
\loadsetups[m-name-of-your-module.xml] % to load the file with definitions
\setup{nameofyourcommand}

An example:

\setuppapersize[A5]
\usemodule[int-load]
\loadsetups
\setup{externalfigure}

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

 \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 simplefonts 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-simplefonts.tex

to get a t-simplefonts.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.

(The autogenerated documentation of all ConTeXt sources has been made available by Luigi at [2]. Go there for examples of the output.)

Legacy modules disclaimer

Prior to release 2005.05.25, ConTeXt silently truncated all file names in \usemodule commands to 8 characters long and lowercased them to "prevent cross platform problems with filenames". Thus, module files that are to be used with older versions of ConTeXt must have filenames that fit those restrictions, or they will (somewhat cryptically) not be found.