4
edits
Changes
Jump to navigation
Jump to search
m
< [[The ConTeXt Way]]
==Installation==
===Basics===
===Installation by hand===
===ConTeXt minimals=standalone==
The complete list of availables modules in minimals is:==ConTeXt LMTX==
* fAs of 2020-urwgaramond* f06-urwgothic* t06, the ConTeXt LMTX distribution does not provide a built-account* t-algorithmic* t-bib* t-bnf* t-chromato* t-cmscbf* t-cmttbf* t-construction-plan* t-degrade* t-fixme* t-french* t-games* t-gnuplot* t-layout* t-letter* t-lettrine* t-lilypond* t-mathsets* t-simplefonts* t-simpleslides* t-taspresent* t-tikz* t-typearea* t-typescripts* t-vimin way to install or update modules. However, (something like) the following can be used to install and update all modules together with the rest of the distribution. The snippet must be run from the toplevel directory of the ConTeXt LMTX distribution, i.e. the directory that contains <tt>install.sh</tt>.
===TeX Live===Because the final <tt>tex/texmf-modules</tt> must contain the union of all individual module directories, the snippet creates and leaves an intermediate <tt>modules</tt> directory in the toplevel directory of the ConTeXt LMTX distribution. There may be a more clever way of using <tt>rsync</tt>, that does not need an intermediate directory. On the other hand, as of 2020-06-06, only 37MB of space are wasted.
==Special Purpose Modules==
==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 ==Module requirements==All modules should start with filenames"a block containing ''meta information'' about that module. Thus, module files that are There is a [[Module template]] available to be used with older versions of ConTeXt must have filenames help setting up that fit those restrictions, or they will (somewhat cryptically) not be foundheader correctly.
<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.
→Installation by hand
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.
The installation of extra files in TeX (called modules in ConTeXt) can be difficult
but their existence depends on the TeX distribution; among these, texmf-local is the most common.
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 pre-created subdirectories you
can unzip the archive in the top-level directory (e.g. texmf-local/) and all
files are on the correct place.
context --generate
Users of the ConTeXt standalone (formerly "minimals dont") distribution don't have to download the module files and unzipthem in the local directory , because they can use the '<tt>first-setup' </tt> script for this.
To install for example the simpleslides modules you write
first-setup.sh --extrasmodules="t-simpleslides"
To install more modules at the same time write
first-setup.sh --extrasmodules="t-simpleslides,t-french" The complete list of availables modules in standalone is: * [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 (some of these are obsolete...)
# Transfer all modules from the ConTeXt Garden. # # No -p (--perms) is given to rsync, because, as of 2020-06-06, many # files (e.g. all files in # modules/t-letter/tex/context/third/letter/style) would come out # world-writeable, which may pose a significant security risk on a # multi-user system. # # The --chmod=D755,F644 may not be necessary. However, as of # 2020-06-06, without it files come out with executable bits set. rsync -rltsv --new-compress --delete --chmod=D755,F644 \ rsync://contextgarden.net/minimals/current/modules/ \ modules # Recreate tex/texmf-modules as an empty directory. WARNING: This # assumes that you have nothing but modules from ConTeXt Garden in # tex/texmf-modules. rm -rf tex/texmf-modules mkdir -p tex/texmf-modules # Create the union of all modules in tex/texmf-modules. for module in modules/* ; do rsync -rlts --exclude=/VERSION ${{Note | description required}module}/ tex/texmf-modules done # Update the ConTeXt LMTX distribution. Alternatively, if you do not # want to do that, you have to run mtxrun --generate. sh ./install.sh Here is a simplified version of this procedure, tested with MacOS 10.15 on 2020-12-12. There doesn't seem to be any perm issues anymore. # Synchronize all modules from the ConTeXt Garden in the directory 'modules', 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 'module's directory to reclaim some space or keep it to speed up the next update. # rm -rf modules # Update the ConTeXt LMTX distribution. # Alternatively, if you do not want to do that, you have to run mtxrun --generate. sh ./install.sh ==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-french
* context-games
* context-gantt
* context-gnuplot
* context-letter
* context-vim
=Usage=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]]* [[source:m-chart.tex|m-chart]]: [[Flow Charts]]* [[source:m-chemic.tex|m-chemic]]: [[Chemistry|PPCHTeX]] (chemical structure formulae)* [[source:m-cweb.tex|m-cweb]]: [[CWEB]] pretty printing* [[source:m-database.tex|m-database]]: creating simple tables (or forwarding data to user-defined commands) using [[m-database|comma/space/tab-separated values]]* [[source:m-dratex|m-dratex]]: loading of DraTeX* [[source:m-edtsnc.tex|m-edtsnc]]: support for editor synchronization, will replace m-pdfsync* [[source:m-educat.tex|m-educat]]: educational additions (for settings school tests or questionaires)* [[source:m-gamma.tex|m-gamma]]: [[Aleph|Omega]] support* [[source:m-graph.tex|m-graph]]: support for [[MetaPost]] graph module* [[source:m-layout.tex|m-layout]]: defines some [[Layout]] presets* [[source:m-level.tex|m-level]]: module for catching nesting errors* [[source:m-narrowtt.tex|m-narrowtt]]: using a narrower [[Latin Modern]] font for verbatim* [[source:m-newmat.tex|m-newmat]]: support for some AMSmath features, is loaded by [[Math with amsl|amsl]], see [[Math with newmat]]* [[source:m-pdfsnc.tex|m-pdfsnc]]: editor/PDF synchronization support (used by iTeXMac and TeXShop)* [[source:m-pictex.tex|m-pictex]]: needed for [[PicTeX]] without eTeX* [[source:m-plus.tex|m-plus]]: loads some extra features (currently empty)* [[source:m-pstric.tex|m-pstric]]: connection macros for [[PSTricks]] (PostScript tricks)* [[source:m-r.tex|m-r]]: typing and executing [http://www.r-project.org/ R] scripts* [[source:m-quest.tex|m-quest]]: module for fill-in forms (dutch only)* [[source:m-steps.tex|m-steps]]: Step Charts, see [[XML]] step charts* [[source:m-streams.tex|m-streams]]: Synchronised typesetting from different sources* [[source:m-subsub.tex|m-subsub]]: Defines 5 extra sectioning levels* [[source:m-tex4ht.tex|m-tex4ht]]: convert a ConTeXt document to html, more about it on [[tex4ht]]* [[source:m-tryout.tex|m-tryout]]: Contains temporary functions for testing* [[source:m-units.tex|m-units]]: Structured input of values with [[units]]* [[source:m-visual.tex|m-visual]]: [[Visual Debugging]] (described in [[This Way]] no.7 [[manual:mag-0007.pdf|Faking Text and More]])
When you load a module with <code>\usemodule[modulename]</code> 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 <code>\usemodule[<prefix>][modulename]</code> =Included Modules=Contributed modules * {{code|bibl-bib.lua}} ({{src|bibl-bib.mkiv}}): [[Bibliography]] (maintained by Taco)* {{code|m-arabtex}} ({{src|m-arabtex.mkii}}): loading of Lagally's [[Arabian and Hebrew|ArabTeX]]* {{code|m-barcodes}} ({{src|m-barcodes.mkiv}}): generate barcodes using PStricks. You should probably use m-zint instead.* {{code|m-chart}} ({{src|m-chart.lua}} {{src|m-chart.mkii}} {{src|m-chart.mkvi}}): [[Flow Charts]]* {{code|m-chemic}} ({{src|m-chemic.mkii}} {{src|m-chemic.mkiv}}): [[Chemistry|PPCHTeX]] (chemical structure formulae) * {{code|m-cweb}} ({{src|m-cweb.tex}}): [[CWEB]] pretty printing* {{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]].* {{code|m-datastrc}} ({{src|m-datastrc.tex}}):* {{code|m-directives}} ({{src|m-directives.mkiv}}):* {{code|m-dratex}} ({{src|m-dratex.mkii}}): loading of DraTeX* {{code|m-edtsnc}} ({{src|m-edtsnc.mkii}}): support for editor synchronization, will replace m-pdfsync* {{code|m-educat}} ({{src|m-educat.tex}}): educational additions (for settings school tests or questionaires)* {{code|m-fields}} ({{src|m-fields.mkiv}}):* {{code|m-format}} ({{src|m-format.tex}}):* <strike>[[source:m-gamma.tex|m-gamma]]: [[Aleph|Omega]] support</strike>* {{code|m-graph}} ({{src|m-graph.mkii}} {{src|m-graph.mkiv}}): support for [[MetaPost]] graph module* {{code|m-ipsum}} ({{src|m-ipsum.mkiv}}): lorem ipsum filler text* {{code|m-layout}} ({{src|m-layout.tex}}): defines some [[Layout]] presets* {{code|m-level}} ({{src|m-level.mkii}}): module for catching nesting errors* {{code|m-logcategories}} ({{src|m-logcategories.mkiv}}):* {{code|m-markdown}} ({{src|m-markdown.lua}} {{src|m-markdown.mkiv}}):* {{code|m-mathcrap}} ({{src|m-mathcrap.mkiv}}):* {{code|m-mkii}} ({{src|m-mkii.mkiv}}):* {{code|m-mkivhacks}} ({{src|m-mkivhacks.mkiv}}):* {{code|m-morse}} ({{src|m-morse.mkvi}}):* {{code|m-narrowtt}} ({{src|m-narrowtt.tex}}): using a narrower [[Latin Modern]] font for verbatim* {{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_-_My_Way#ThisWay|ThisWay]] no.7 [[magazine:0007|Faking Text and More]])* {{code|m-zint}} ({{src|m-zint.mkiv}}): Generate [[Barcodes|barcodes]] using [http://www.zint.org.uk zint] =Contributed Modules=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}}
* [[Math with amsl|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)
* [[Modules/Karnaugh|Karnaugh]]: draws Karnaugh maps
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 <code>$TEXMF/tex/context/third</code> then run <code>luatools --generate</code>.
The following modules implement special formatting requirement for journals or magazines. These modules are distributed with ConTeXt, so you need not download anything.
* [[Modules/This Way - My Way#MyWay|MyWayMy Way]] , User documentation on ConTeXt
* [[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)
Do not forget to specify a ''license'' as the permitted modes of distribution
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.
==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]). Probably one day this will become Its purpose is a comprehensive listing of the optional and non-optionalarguments that a macro defined in the module accepts.From the interface a part good deal of documentation can be auto-generated,as are for instance the [http://texshowpragma-ade.nl/general/qrcs/setup-en.pdf ConTeXt Quick Reference]and the initial input of the [http://wiki.contextgarden.net/ texshowCategory:Reference/en Command Reference] and will also be easy-to-edit,which itself started as a wikification of the now obsolete ''TeXShow''.
When documenting your module, you can use
An example:
<context source="yes">
\setuppapersize[A5]
\usemodule[int-load]
\loadsetups
</context>
By default, this places a frame around the setup. If you want to get gray backgroudbackground, as in the context documentation, add the following
<texcode>
\setupframedtexts
[setuptext]
[background=screencolor, backgroundcolor=lightgray,
frame=off]
</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 – sparse
– 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}} 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.
