Command

ConTeXt command reference

Newly created ConTeXt command reference pages (pages with prefix /Command in their title) are a little different from all other pages on this wiki. They look like normal wiki pages when viewing, but the source is in fact an XML file that is derived from the interface xml files in the ConTeXt distribution (see below for legacy pages).

The new pages are controlled by the ConTeXtXML wiki extension. The extension takes care of the conversion from XML to HTML for viewing, and will automatically update the page source if there are some changes in the command definition in the ConTeXt distribution. Also, it stores the page in XML format on the harddisk of the server, so that it can be used in other documentation efforts like a proper reference manual. More details about how that all works can be found in the ConTeXtXML extension page.

As a result of the extra management layer and the XML format, some extra care is needed when editing the /Command pages, and that is explained in Help:Command.

About page names

Simple commands

Simple commands like \setuphead have a simple page name as well: /Command/setuphead (\setuphead).

Environments

Environments like \starttext ... \stoptext have a page based on the starting command: /Command/starttext (\starttext).

Generated commands and environments

In ConTeXt, some commands and environments are created by use of another command, typically by a command whose name starts with \define.... Users are free to define their own commands and environments that way, but some such are in fact predefined by ConTeXt itself. Examples are \startchapter, which is defined using \definesection[chapter], and \startitemize, which is defined using \defineitemgroup[itemize].

In the XML documentation generated commands like \startchapter and \startsubject are grouped together, because all commands generated by \definesection have the exact same parameters and options.

To mimic this on the wiki, for generated commands there is a single page for the group. For these group pages, the page name starts with an underscore. For the sectioning example, that is /Command/_startsection. There are also the pages /Command/startchapter (\startchapter) and /Command/startsubject (\startsubject), but these are just redirect pages to /Command/_startsection (\_startsection).

As you can see above, Using the {{cmd}} template for referring to the group pages looks a bit weird ({{cmd|_startsection}} was given) which is why there is a separate template for referring to those group pages: {{gen}}. {{gen|startsection}} produces: startsection.

Page structure

The structure of the new command pages is always the same:

Table of Contents	All Command pages have a toc.
Command title	Nicely formatted title.
Summary	A short line explaining the command's use.
Instances	Only for grouped pages. If there are any predefined instances, they are listed in a table here.
Settings	The syntax table, and the documentation for various options and arguments right below. This section may be repeated in cases where a command has different ways of using it.
Description	The main documentation of the command.
Examples	Examples, each one in a separate subheading.
Notes	Any special notes, like 'available since XXXX'.
See also	Links to other relevant places.
Forum help	A list of quick-links to community searches.

The syntax table in Settings, in detail

A table that is set up along the following lines.

\XXX[...][...][...]
[...]	text
key	default variant other
[...]	text

Let us examine the following example:

\placefloat[...][...,...][...,...]{...}{...}
[...]	singular
[...,...]	split always left right inner outer backspace cutspace inleft inright inmargin leftmargin rightmargin leftedge rightedge innermargin outermargin inneredge outeredge text opposite reset height depth [+-]line halfline grid high low fit 90 180 270 nonumber none local here force margin [+-]hang hanging tall both middle offset top bottom auto page leftpage rightpage somewhere effective header footer tblr lrtb tbrl rltb fxtb btlr lrbt btrl rlbt fxbt fixd
[...,...]	reference
{...}	text
{...}	content

You would not normally type \placefloat in your TeX-text, but rather a previously defined kind of float (figure, for example). If you did use \placefloat literally, then the first argument would be the name of the predefined kind of float, like figure.

But normally, the command to use in a document would be \placefigure:

\placefigure[...,...][...,...]{...}{...}
[...,...]	split always left right inner outer backspace cutspace inleft inright inmargin leftmargin rightmargin leftedge rightedge innermargin outermargin inneredge outeredge text opposite reset height depth [+-]line halfline grid high low fit 90 180 270 nonumber none local here force margin [+-]hang hanging tall both middle offset top bottom auto page leftpage rightpage somewhere effective header footer tblr lrtb tbrl rltb fxtb btlr lrbt btrl rlbt fxbt fixd
[...,...]	reference
{...}	text
{...}	content
instance of placefloat, generated by \definefloat

The first two arguments of \placefigure are optional (recognisable because they are slanted), the second two are mandatory. The first optional argument takes one of the keywords mentioned in \placefloat. If the argument is not given, then it uses the keyword in bold (assuming there is one). reference stands for a reference label; just insert a name that you want to refer to later. In the third and fourth argument text is in italics (to indicate that it is not the keyword text, which does exist). Rather, it is a (terse) description of what you can enter. In this case, you can enter any kind of text. content is similar.

To get syntax tables like the ones above easily in a different page, add

  <syntax>placefloat</syntax>

where you need it. This will fetch the relevant table(s) from the command database.

Pre-existing pages

The behaviour of pages that were already in existence before the ConTeXtXML extension took over management does not change. They can still be edited as normal wiki pages.

We of course want such pages to be converted into the new format. The recipe for that is:

• Move the existing page away to e.g. Command_old/setuphead (this can be done via the More dropdown at the top of the page).
  Make sure you uncheck the leave a redirect box, or you will first have to delete that redirect again using the More dropdown at the top of the page.

The goal of the previous step is to make Command/setuphead temporarily be a 'Missing page', so that the extension can initialise it.

• Now go to the Command/setuphead url.
  If you followed a wiki link, it should automatically open the editor. Otherwise, click on the Create link.
  The edit screen will automatically be filled with a form that is suitable for the command you are editing.
• If the Edit field is missing but you see an error that states Command not found, you are trying to document a no longer existing command, and you should ask for advice on the mailing list.
• If the Edit field contains a #REDIRECT line this command that is generated (as explained above). Save the redirect, then continue with editing the target page.
• Open Command_old/setuphead in a different browser window, and copy the documentation therein into the proper spots of the new Command/setuphead page.
• Save the new Command/setuphead, and delete the Command_old/setuphead page (this can also be done via the More dropdown at the top of the page)

If you want to help

there are three pages with specifics about what needs to be checked, converted or added:

• Document level commands work page (most important, especially the existing pages that should be converted)
• Style level commands work page (somewhat less but still quite important)
• System level commands work page (somewhat less but still quite important)

When you have done some work, please update the relevant one of those three overview pages. Also, if you think it will take some time, place a remark in that overview page beforehand to let others know what you are working on.