188
edits
Changes
Jump to navigation
Jump to search
→Modules writing guidelines: docstrings
documentation online, so feel free to relay your questions to
the [[ConTeXt_Mailing_Lists|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.
===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.
