Help:Command reference

From ConTeXt wiki
(Redirected from Help:Reference)

This page is about editing command reference pages. For editing this wiki in general, see ConTeXt_wiki:Editing.

The command reference pages under Commands have a common structure: a rather typical syntax usage table at the top, followed by a description, some examples, and suggestions for other pages to look at. These sections are described below.

If you want to create a new command page, skip ahead to the Command page template section below.

The structure of a command reference page

Syntax

A table, implemented in HTML for now, that is set up along the following lines.

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

Let us examine the following example:

\placefloat[...,...][...,...]{...}{...}
[...,...]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
[...,...]reference
{...}text
{...}CONTENT


\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
[...,...]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[...,...][...,...]{...}{...}
instance of \placefloat


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 isa (terse) description of what you can enter. In this case, you can enter any kind of text. CONTENT is similar.

This is for describing what the command does. How does it affect the layout? Does it create other commands, like \defineparagraphs[MyPars] creates \startMyPars and \setupMyPars? Does it need specific circumstances, like \setuparranging[XY] requires \setuppaper[nx=..., ny=...] to be set first?

To get syntax tables like the ones above easily, add

  <syntax>placefloat</syntax>

to the text in your Syntax section. This will fetch the relevant HTML table(s) from the command database.

Example

Preferably a compiled example created with <context source=yes>...</context>, but if the example won't compile, or the result does not display well, then <texcode>...</texcode> is also acceptable.

See also

You want a bulleted list here, practically always. Link to commands with the {{cmd}} template, to the relevant source files with the {{src}} template, and to pages with ordinary [[wikilinks]].

Categories

All commands should have at least one category link of the form [[Category:Command/Subcategory|somecommand]]. You can visit Category:Commands to see the ones that are not yet categorized. Putting a page in multiple categories is encouraged.

Navboxes

See {{Columns navbox}} for an example, and Wikiproject Navboxes for navboxes in general. The eventual intention is to have a navbox on every page, with three (or four groups) in it:

  • Topic articles
  • Commands
  • Example snippets
  • (PDF manuals)

This would neatly bind together the various kinds of documentation this wiki provides, and equally bind together related commands and pages, and look neat on every page.

Command page template

To create a new command page, navigate to the page you want to create, (e.g. Command/thecommandinquestion,) and copy the template below. The {{subst:SUBPAGENAME}} template means the insertion of the proper command name is taken care of. Unfortunately, that replacement takes place at the wrong moment for the syntax command, so you will have to insert that one by hand.

{{Reference
|name={{subst:SUBPAGENAME}}
|attributes=
}}

== [[Help:Reference|Syntax]] (automatically generated) ==

<syntax>...</syntax>

== Description == 


== Example ==
<!-- something like this:
<context source=yes>
...
</context>
Or use <texcode> tags if the example doesn't compile on this wiki
-->

== See also ==
<!-- something like this:
* {{cmd|setuphead}}
* {{src|strc-sec.mkiv#l299}}
-->

== Help from ConTeXt-Mailinglist/Forum ==
All issues with:
{{Forum|{{subst:SUBPAGENAME}}}}

[[Category:Commands|{{subst:SUBPAGENAME}}]]