Difference between revisions of "Modules"

From Wiki
Jump to navigation Jump to search
(Define module release file. Explain module publishing.)
Line 261: Line 261:
 
* [[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)
  
−
=Modules writing guidelines=
+
=Module writing guidelines=
  
 
==Module requirements==
 
==Module requirements==
−
All modules should start with a block containing ''meta information'' about that module.
+
 
 +
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 sort these files in folders according to TDS (TeX directory structure) – just have a look at the distribution. BTW <tt>t-</tt> is for “third party” modules, that means everything that isn’t part of the distribution.
 +
 
 +
=== Module release file ===
 +
 
 +
* 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 an 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 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.
 
There is a [[Module template]] available to help setting up that header correctly.
  
Line 354: Line 370:
 
Which should generate a font-def.pdf in your current directory.
 
Which should generate a font-def.pdf in your current directory.
  
 +
<!-- offline as of 2023-04
 
(The autogenerated documentation of all ConTeXt sources has been
 
(The autogenerated documentation of all ConTeXt sources has been
 
made available by Luigi at [http://foundry.supelec.fr/gf/project/modules/].
 
made available by Luigi at [http://foundry.supelec.fr/gf/project/modules/].
 
Go there for examples of the output.)
 
Go there for examples of the output.)
 +
-->
 +
 +
==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).
  
−
==Legacy modules disclaimer==
+
* Create a '''new module''' entry with a distinct name (e.g. prettyprinter) and fill in the metadata:
−
<!-- This info is obsolete, the section could be kicked out, doesn’t it? -->
+
** Title, e.g. “My Pretty Printer”
−
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.
+
** 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. “<tt>/macros/context/contrib/context-prettyprinter</tt>”
 +
** 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

Revision as of 11:39, 14 April 2023

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 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.

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...)

ConTeXt LMTX

As of 2020-06-06, the ConTeXt LMTX distribution does not provide a built-in 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 install.sh.

Because the final tex/texmf-modules must contain the union of all individual module directories, the snippet creates and leaves an intermediate modules directory in the toplevel directory of the ConTeXt LMTX distribution. There may be a more clever way of using rsync, that does not need an intermediate directory. On the other hand, as of 2020-06-06, only 37MB of space are wasted. 

 # 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 ${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-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)
  • 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 $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.

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 sort these files in folders according to TDS (TeX directory structure) – just have a look at the distribution. BTW t- is for “third party” modules, that means everything that isn’t part of the distribution.

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 an 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 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.


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
Retrieved from "https://wiki.contextgarden.net/index.php?title=Modules&oldid=33905"