Difference between revisions of "Modules"
(Define module release file. Explain module publishing.) |
(new module installer script; restructuring & removing outdated information) |
||
Line 1: | Line 1: | ||
− | Modules are extensions to | + | Modules are extensions to ConTeXt’s core functions. |
− | There are not as many modules for ConTeXt as packages for LaTeX, because a lot | + | 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= | =Installation= | ||
Line 21: | Line 21: | ||
* texmf-project | * texmf-project | ||
− | but their existence depends on the TeX distribution; | + | but their existence depends on the TeX distribution; among these, texmf-local is the most common. |
==Installation by hand== | ==Installation by hand== | ||
− | When you want to install a new module | + | When you want to install a new single-file module, create |
− | the subdirectories in the way described above and place the file there | + | 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 --generate | ||
− | + | (ConTeXt doesn’t use `ls-R` files or `kpsewhich` any more.) | |
− | + | ==Installation by script (LMTX)== | |
− | + | As of 2023-05-07, 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. | |
− | + | mtxrun --script install-modules --list | |
− | + | 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 <tt>install.sh</tt>. | ||
− | + | Because the final <tt>tex/texmf-modules</tt> must contain the union of all individual module directories, the commands create and leave an intermediate <tt>modules</tt> 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. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | # Synchronize all modules from | ||
rsync --recursive --links --times --info=progress2,remove,symsafe,flist,del --human-readable --del rsync://contextgarden.net/minimals/current/modules/ modules | 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 | + | # 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 | + | # If you have personal modules in tex/texmf-modules, they won’t be modified. |
mkdir -p tex | mkdir -p tex | ||
rsync -rlt --exclude=/VERSION --del modules/*/ tex/texmf-modules | rsync -rlt --exclude=/VERSION --del modules/*/ tex/texmf-modules | ||
− | # You may delete the ' | + | # You may delete the 'modules' directory to reclaim some space or keep it to speed up the next update. |
# rm -rf modules | # rm -rf modules | ||
− | # Update the ConTeXt | + | # Update the ConTeXt file database. |
− | + | mtxrun --generate | |
− | + | ||
− | + | ||
+ | ==Installation by script (MkIV) == | ||
+ | |||
+ | Users of the ConTeXt MkIV standalone can use the <tt>first-setup</tt> 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== | ||
− | TeX Live is a large TeX distribution for most | + | 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. |
+ | <!-- | ||
The following modules are available: | The following modules are available: | ||
Line 168: | Line 101: | ||
* context-typearea | * context-typearea | ||
* context-vim | * context-vim | ||
+ | --> | ||
=Usage= | =Usage= | ||
Line 173: | Line 107: | ||
When you load a module with <code>\usemodule[modulename]</code> ConTeXt looks for a file with the following names: | When you load a module with <code>\usemodule[modulename]</code> ConTeXt looks for a file with the following names: | ||
− | * m- | + | * m-modulename (core module) |
* p-modulename (private module) | * p-modulename (private module) | ||
* s-modulename (ConTeXt style file) | * s-modulename (ConTeXt style file) | ||
* x-modulename (XML module) | * x-modulename (XML module) | ||
− | * t-modulename (Third party module) | + | * t-modulename ("Third party" contributed module) |
* modulename | * modulename | ||
− | Once a file is found ConTeXt stops the search and loads the found file (only once). | + | Once a file is found, ConTeXt stops the search and loads the found file (only once). |
− | When you have two | + | When you have two files with the same name but different prefixes, you can tell ConTeXt which file it should load with |
<code>\usemodule[<prefix>][modulename]</code> | <code>\usemodule[<prefix>][modulename]</code> | ||
Line 240: | Line 174: | ||
=Contributed Modules= | =Contributed Modules= | ||
− | For a list of contributed modules see | + | For a list of contributed modules see [http://modules.contextgarden.net the modules section] on contextgarden.net: |
− | {{ | + | * [http://modules.contextgarden.net/account t-account] draw T-accounts |
+ | * [http://modules.contextgarden.net/algorithmic t-algorithmic] like LaTeX algorithmic | ||
+ | * [http://modules.contextgarden.net/animation t-animation] create animations | ||
+ | * [http://modules.contextgarden.net/annotation t-annotation] todo lists | ||
+ | * [http://modules.contextgarden.net/t-bnf t-bnf] BNF grammar | ||
+ | * [http://modules.contextgarden.net/chromato t-chromato] chromatograms | ||
+ | * [http://modules.contextgarden.net/cmscbf t-cmscbf] bold small caps | ||
+ | * [http://modules.contextgarden.net/cmttbf t-cmttbf] bold typewriter | ||
+ | * [http://modules.contextgarden.net/t-construction-plan t-construction-plan] figures with defined scale | ||
+ | * [http://modules.contextgarden.net/t-degrade t-degrade] degrading JPEG images | ||
+ | * [http://modules.contextgarden.net/fancybreak t-fancybreak] thought breaks | ||
+ | * [http://modules.contextgarden.net/filter t-filter] run external programs on inline code | ||
+ | * [http://modules.contextgarden.net/fixme t-fixme] like LaTeX fixme | ||
+ | * [http://modules.contextgarden.net/t-french t-french] | ||
+ | * [http://modules.contextgarden.net/fullpage t-fullpage] | ||
+ | * [http://modules.contextgarden.net/games t-games] board games | ||
+ | * [http://modules.contextgarden.net/gantt t-gantt] Gantt charts | ||
+ | * [http://modules.contextgarden.net/gnuplot t-gnuplot] include GNUplot graphics | ||
+ | * [http://modules.contextgarden.net/t-layout t-layout] | ||
+ | * [http://modules.contextgarden.net/letter t-letter] formal letters | ||
+ | * [http://modules.contextgarden.net/t-lettrine t-lettrine] decorative paragraph starts (initials) | ||
+ | * [http://modules.contextgarden.net/t-lilypond t-lilypond] include musical scores with GNU LilyPond | ||
+ | * [http://ctan.org/pkg/markdown t-markdown] render markdown documents | ||
+ | * [http://modules.contextgarden.net/mathsets t-mathsets] mathematical sets, probabilities etc. | ||
+ | * [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-pgfplots | ||
+ | * [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 | ||
+ | <!-- | ||
* [[Extended description|xdesc]] (extended description, e.g. for epigrams) | * [[Extended description|xdesc]] (extended description, e.g. for epigrams) | ||
* [[Math with nath|nath]] (natural math, see [[Math]]) | * [[Math with nath|nath]] (natural math, see [[Math]]) | ||
Line 250: | Line 218: | ||
* [[Modules/Karnaugh|Karnaugh]]: draws Karnaugh maps | * [[Modules/Karnaugh|Karnaugh]]: draws Karnaugh maps | ||
− | |||
− | |||
− | |||
=Special Purpose Modules= | =Special Purpose Modules= | ||
Line 260: | Line 225: | ||
* [[Modules/Pracjourn|pracjourn]] Articles for [http://tug.org/pracjourn/ The PracTeX Journal] | * [[Modules/Pracjourn|pracjourn]] Articles for [http://tug.org/pracjourn/ The PracTeX Journal] | ||
* [[Modules/Maps|maps]] Articles for [http://www.ntg.nl/maps.html MAPS], the publication of NTG (Nederlandstalige TeX Gebruikersgroep or Netherlands TeX Group) | * [[Modules/Maps|maps]] Articles for [http://www.ntg.nl/maps.html MAPS], the publication of NTG (Nederlandstalige TeX Gebruikersgroep or Netherlands TeX Group) | ||
+ | --> | ||
=Module writing guidelines= | =Module writing guidelines= | ||
Line 265: | Line 231: | ||
==Module requirements== | ==Module requirements== | ||
− | While a module usually consists of one main file with a name like <tt>t-modulename.[tex|ctx|mkiv|mkxl]</tt>, there can be many more files, and there should be some documentation. Please | + | While a module usually consists of one main file with a name like <tt>t-modulename.[tex|ctx|mkiv|mkxl]</tt>, there can be many more files, and there should be some documentation. Please adhere to the filename convention 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 release file === | === Module release file === | ||
* A release file is a ZIP archive that contains the necessary files in a TDS compliant structure. | * A release file is a ZIP archive that contains the necessary files in a TDS compliant structure. | ||
− | * The filename should be <code>t-modulename-version.zip</code>, where the version is usually | + | * The filename should be <code>t-modulename-version.zip</code>, where the version is usually a date like <tt>YYYY.MM.DD</tt> (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 must be a VERSION file that only contains your version string. | ||
* On the top level there should be a LICENSE file containing the text of an open source license of your choice. | * On the top level there should be a LICENSE file containing the text of an open source license of your choice. | ||
Line 291: | Line 259: | ||
Including the full text of your license in your source repo is best practice. | 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 | + | In order to avoid ''conflicting macros'' it is essential for a module that it adheres |
to the [[Module_Namespaces|namespace convention]]. | 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. | 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. | ||
Line 299: | Line 267: | ||
(as in [http://source.contextgarden.net/tex/context/interface/cont-en.xml /tex/context/interface/cont-en.xml]). | (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 | Its purpose is a comprehensive listing of the optional and non-optional | ||
− | arguments | + | arguments accepted by macros defined in the module. |
+ | |||
From the interface a good deal of documentation can be auto-generated, | From the interface a good deal of documentation can be auto-generated, | ||
as are for instance the [http://pragma-ade.nl/general/qrcs/setup-en.pdf ConTeXt Quick Reference] | as are for instance the [http://pragma-ade.nl/general/qrcs/setup-en.pdf ConTeXt Quick Reference] | ||
Line 320: | Line 289: | ||
</context> | </context> | ||
− | By default, this places a frame around the setup. If you want to get gray background, as in the | + | 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: |
<texcode> | <texcode> | ||
Line 330: | Line 299: | ||
</texcode> | </texcode> | ||
− | Apart from the existing XML files in the ConTeXt tree there is little | + | Apart from the existing XML files in the ConTeXt tree, there is little |
documentation online, so feel free to relay your questions to | documentation online, so feel free to relay your questions to | ||
the [[Mailing list|mailing list]]. | the [[Mailing list|mailing list]]. | ||
Line 338: | Line 307: | ||
implementation details and other peculiarities the reader should be | implementation details and other peculiarities the reader should be | ||
aware of. | aware of. | ||
+ | |||
In <tt>.tex</tt> files (and other files containing primarily TeX code, e.g. | 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> | <tt>.mki[iv]</tt>) any line beginning with the comment leader <tt>%D</tt> | ||
will be treated as such a docstring. | will be treated as such a docstring. | ||
Formatting is done via ordinary TeX commands. | Formatting is done via ordinary TeX commands. | ||
+ | |||
In Lua files (e.g. <tt>.cld</tt>) multi-line comments start with | In Lua files (e.g. <tt>.cld</tt>) multi-line comments start with | ||
<tt>--[[ldx--</tt> and end with <tt>--ldx]]--</tt>. | <tt>--[[ldx--</tt> and end with <tt>--ldx]]--</tt>. | ||
Line 353: | Line 324: | ||
* [[source:x-ldx.ctx|<tt>x-ldx.ctx</tt>]] for Lua files, and | * [[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. | * [[source:s-mod.ctx|<tt>s-mod.ctx</tt>]] for TeX files. | ||
+ | |||
Thus, in order to generate the documentation for the | Thus, in order to generate the documentation for the | ||
− | + | ''simplefonts'' module you first have to `chdir` to the <tt>files</tt> subdirectory of | |
− | module you first have to chdir to the <tt>files</tt> subdirectory of | ||
your checkout. | your checkout. | ||
+ | |||
Next you run the pretty printer on its main file | Next you run the pretty printer on its main file | ||
<pre> | <pre> | ||
Line 363: | Line 335: | ||
to get a <tt>t-simplefonts.pdf</tt> which contains the – sparse | to get a <tt>t-simplefonts.pdf</tt> which contains the – sparse | ||
– annotations in serif and the actual code as colorful listing. | – 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 | Likewise the processing of Lua code, e.g. <tt>[[source:font-def.lua|font-def.lua]]</tt> from | ||
the main ConTeXt tree: | the main ConTeXt tree: | ||
Line 369: | Line 342: | ||
</pre> | </pre> | ||
Which should generate a font-def.pdf in your current directory. | Which should generate a font-def.pdf in your current directory. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==Publication and maintenance== | ==Publication and maintenance== | ||
Line 382: | Line 349: | ||
* If you lost your password, please ask Taco or Mojca (via the mailing list if you don’t know them). | * If you lost your password, please ask Taco or Mojca (via the mailing list if you don’t know them). | ||
− | * Create a '''new module''' entry with a distinct name (e.g. | + | * Create a '''new module''' entry with a distinct name (e.g. “prettyprinter”) and fill in the metadata: |
** Title, e.g. “My Pretty Printer” | ** Title, e.g. “My Pretty Printer” | ||
** Short and longer description (the short one gets published e.g. in CTAN updates). | ** Short and longer description (the short one gets published e.g. in CTAN updates). | ||
Line 390: | Line 357: | ||
** Works with Mk... (please check) | ** Works with Mk... (please check) | ||
** License | ** License | ||
− | ** Check | + | ** Check “Put in download section” (yes please, allows installation by rsync) |
− | ** Check | + | ** Check “Put in ConTeXt distribution” (not sure if this works) |
− | ** Check | + | ** Check “Synch with CTAN” (yes please, makes it visible) |
** CTAN location: e.g. “<tt>/macros/context/contrib/context-prettyprinter</tt>” | ** CTAN location: e.g. “<tt>/macros/context/contrib/context-prettyprinter</tt>” | ||
** Comment: for you or the server admins | ** Comment: for you or the server admins |
Revision as of 17:46, 7 May 2023
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.
Contents
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)
As of 2023-05-07, 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.
mtxrun --script install-modules --list
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
bibl-bib.lua
(bibl-bib.mkiv): Bibliography (maintained by Taco)m-arabtex
(m-arabtex.mkii): loading of Lagally's ArabTeXm-barcodes
(m-barcodes.mkiv): generate barcodes using PStricks. You should probably use m-zint instead.m-chart
(m-chart.lua m-chart.mkii m-chart.mkvi): Flow Chartsm-chemic
(m-chemic.mkii m-chemic.mkiv): PPCHTeX (chemical structure formulae)m-cweb
(m-cweb.tex): CWEB pretty printingm-database
(m-database.lua m-database.mkii m-database.mkiv): creating simple tables (or forwarding data to user-defined commands) using comma/space/tab-separated values. Wiki: M-database.m-datastrc
(m-datastrc.tex):m-directives
(m-directives.mkiv):m-dratex
(m-dratex.mkii): loading of DraTeXm-edtsnc
(m-edtsnc.mkii): support for editor synchronization, will replace m-pdfsyncm-educat
(m-educat.tex): educational additions (for settings school tests or questionaires)m-fields
(m-fields.mkiv):m-format
(m-format.tex):m-gamma: Omega supportm-graph
(m-graph.mkii m-graph.mkiv): support for MetaPost graph modulem-ipsum
(m-ipsum.mkiv): lorem ipsum filler textm-layout
(m-layout.tex): defines some Layout presetsm-level
(m-level.mkii): module for catching nesting errorsm-logcategories
(m-logcategories.mkiv):m-markdown
(m-markdown.lua m-markdown.mkiv):m-mathcrap
(m-mathcrap.mkiv):m-mkii
(m-mkii.mkiv):m-mkivhacks
(m-mkivhacks.mkiv):m-morse
(m-morse.mkvi):m-narrowtt
(m-narrowtt.tex): using a narrower Latin Modern font for verbatimm-newmat
(m-newmat.tex): support for some AMSmath features, is loaded by amsl, see Math with newmatm-ntb-to-xtb
(m-ntb-to-xtb.mkiv):m-obsolete
(m-obsolete.mkii m-obsolete.mkiv):m-oldfun
(m-oldfun.mkiv):m-oldnum
(m-oldnum.mkiv):m-pdfsnc
(m-pdfsnc.mkii): editor/PDF synchronization support (used by iTeXMac and TeXShop)m-pictex
(m-pictex.tex): needed for PicTeX without eTeXm-plus: loads some extra features (currently empty)m-pstricks
(m-pstricks.lua m-pstricks.mkii m-pstricks.mkiv):m-punk
(m-punk.mkiv):m-quest: module for fill-in forms(dutch only)m-r
(m-r.tex): typing and executing R scriptsm-spreadsheet
(m-spreadsheet.lua m-spreadsheet.mkiv):m-steps
(m-steps.lua m-steps.mkii m-steps.mkvi): Step Charts, see XML step chartsm-streams
(m-streams.tex): Synchronised typesetting from different sourcesm-subsub
(m-subsub.tex): Defines 5 extra sectioning levelsm-tex4ht
(m-tex4ht.mkii): convert a ConTeXt document to html, more about it on tex4htm-timing
(m-timing.mkiv):m-trackers
(m-trackers.mkiv):m-translate
(m-translate.mkiv):m-units
(m-units.mkii m-units.mkiv): Structured input of values with unitsm-visual
(m-visual.mkii m-visual.mkiv): Visual Debugging (described in ThisWay no.7 Faking Text and More)m-zint
(m-zint.mkiv): Generate barcodes using zint
Contributed Modules
For a list of contributed modules see the modules section on contextgarden.net:
- t-account draw T-accounts
- t-algorithmic like LaTeX algorithmic
- t-animation create animations
- t-annotation todo lists
- t-bnf BNF grammar
- t-chromato chromatograms
- t-cmscbf bold small caps
- t-cmttbf bold typewriter
- t-construction-plan figures with defined scale
- t-degrade degrading JPEG images
- t-fancybreak thought breaks
- t-filter run external programs on inline code
- t-fixme like LaTeX fixme
- t-french
- t-fullpage
- t-games board games
- t-gantt Gantt charts
- t-gnuplot include GNUplot graphics
- t-layout
- t-letter formal letters
- t-lettrine decorative paragraph starts (initials)
- t-lilypond include musical scores with GNU LilyPond
- t-markdown render markdown documents
- t-mathsets mathematical sets, probabilities etc.
- t-pararef \startParagraph, 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-pgfplots
- t-ruby Ruby markup (for Chinese, not programming language)
- t-simplefonts simplified font mechanism
- t-simpleslides presentations
- t-typearea like LaTeX/KoMa typearea
- t-typescripts collection of typescripts
- t-urwgaramond
- t-urwgothic
- t-vim syntax highlighting using vim’s syntax files
Module writing guidelines
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 convention 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 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 LICENSE file containing the text of an open source license of your choice.
- 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 must NOT be a folder with the module name, but TDS folders like "doc" and "tex".
The same applies for git/SVN repositories containing ConTeXt modules.
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.
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[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 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
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.
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).
- Create a new module entry with a distinct name (e.g. “prettyprinter”) and fill in the metadata:
- Title, e.g. “My Pretty Printer”
- 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.
- Keywords (for CTAN search)
- Type: Macro or font
- Works with Mk... (please check)
- License
- Check “Put in download section” (yes please, allows installation by rsync)
- 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-prettyprinter”
- 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