Difference between revisions of "Help:Command"

From Wiki
Jump to navigation Jump to search
(implementation notes moved)
 
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{todo|This page documents the situation that will become active in a few days/a week when a newly developed wiki extension will be ported over from the test wiki. This page is written in preparation. Soon, this todo block will be deleted.
 
 
We have a heatwave right now, and even though there are some things in the extension that I still want to improve on, it is too hot in the actual office to do any programming. Instead, I am on the couch in front of a fan.
 
 
--[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 22:52, 9 August 2020 (CEST)}}
 
  
 
== Common problems ==
 
== Common problems ==
Line 9: Line 4:
 
Normally, a page like this would start with a simple introduction and hide the issues at the bottom. But if you are not familiar with editing XML and/or how the [[Command]] setup works, you are very likely to see errors before you have read the rest of this page. So here we go:
 
Normally, a page like this would start with a simple introduction and hide the issues at the bottom. But if you are not familiar with editing XML and/or how the [[Command]] setup works, you are very likely to see errors before you have read the rest of this page. So here we go:
  
* '''I tried to create a new page but the form loads up empty.'''
+
* '''I tried to create a new page but the form shows an error immediately.'''
: You tried to create a page for a ConTeXt command that is not documented in the interface files. Check that you didn't make a typing error first. Alternatively, it is possible that the ConTeXt command is a generated instance, and in that case the page should be a `<nowiki>#REDIRECT</nowiki>`. If neither are the case or you are unsure, ask for advice on the mailing list.
+
: You tried to create a page for a ConTeXt command that is not documented in the interface files. Check that you didn't make a typing error first. If this is not the case or you are unsure, ask for advice on the mailing list.
 
* '''When saving my edit, I see some red text with an XML error.'''
 
* '''When saving my edit, I see some red text with an XML error.'''
: [[Command]] pages must be either well-formed XML, or nothing but a `<nowiki>#REDIRECT</nowiki>`. You likely made a booboo with an XML tag or have an unquoted `<` or `>` or `&` somewhere. Only the content of  `<nowiki><xmlcode></nowiki>`, `<nowiki><texcode></nowiki>`, and `<nowiki><context></nowiki>` are exempt from the normal XML rules (but on the downside, they cannot be nested). You will need to properly quote any attributes, though. And note that <nowiki><pre></nowiki> and <nowiki><code></nowiki> content should be properly quoted as well.
+
: Internally, [[Command]] pages must be either well-formed XML, or nothing but a `<nowiki>#REDIRECT</nowiki>`. You likely made a booboo with an XML tag or have an unquoted `<` or `&` somewhere. Only the content of  `<nowiki><xmlcode></nowiki>`, `<nowiki><texcode></nowiki>`, and `<nowiki><context></nowiki>` are exempt from the normal XML rules (but on the downside, they cannot be nested). You will need to properly quote any attribute values, though. And note that <nowiki><pre></nowiki> and <nowiki><code></nowiki> content should be properly quoted as well.
* '''I tried to edit a section, but I see an error that says 'Section not found'.'''
+
* '''After preview, when saving my edit, I see some red text with an XML error about a stray `<` or `&`.'''
: Only the predefined top-level sections can be edited separately (this limitation is likely to stay).
+
: Because of the special handling of `<nowiki><xmlcode></nowiki>`, `<nowiki><texcode></nowiki>`, and `<nowiki><context></nowiki>`, sometimes the preview resolves entity references outside of `<nowiki><xmlcode></nowiki>`, `<nowiki><texcode></nowiki>`, and `<nowiki><context></nowiki>` into their replacement. Sorry, you will have to go through again and replace the indicated `<`'s and `&`'s back to an entity reference (this is a bug, but it is one that is very hard to fix). If all else fails: use `<nowiki><lt/></nowiki>` and `<nowiki><amp/></nowiki>` instead of XML entities.
* '''I get a warning that the revision is outdated at the top of the edit screen'''
+
* '''I get a warning that the revision is outdated.'''
 
: This happens when the command definition has been updated externally, for example after a new ConTeXt distribution has been installed on the server. The warning should be harmless (this warning is likely to be removed in the future)
 
: This happens when the command definition has been updated externally, for example after a new ConTeXt distribution has been installed on the server. The warning should be harmless (this warning is likely to be removed in the future)
 +
* '''The preview does not show my edit properly.'''
 +
: [[Command]] pages must resolve into well-formed XML. Try to save your edit, and you will almost certainly see a XML error that is preventing the preview from working properly.
  
 
== Introduction ==
 
== Introduction ==
Line 22: Line 19:
 
The pages under [[Command]] are managed by a plugin that saves the page body either as an XML interface documentation record or as a redirect. So, a page under control of the plugin:
 
The pages under [[Command]] are managed by a plugin that saves the page body either as an XML interface documentation record or as a redirect. So, a page under control of the plugin:
  
* should be XML with the `<cd:commandgroup>` top-level tag.
+
* is an XML snippet with the `<cd:commandgroup>` top-level tag,
* or a single line with a `<nowiki>#REDIRECT</nowiki>` to another page
+
* or a `<nowiki>#REDIRECT</nowiki>` to another page.
 +
 
 +
For the redirect case, you will see the standard wiki edit dialog. For the XML case, a dedicated form is provided with sections that can be hidden / shown by clicking on the form section title.
  
The documentation inside the XML tree can make use of (some) wiki markup, as explained below.
+
The documentation inside the XML form can make use of (some) wiki markup, as explained below.
  
Editing a [[Command]] page will normally result in an automatically filled edit screen. The extension has a database of all the command definitions from the ConTeXt distribution, and it will preload the wanted database record in the Edit field when a previously non-existing page is requested.  
+
Starting to edit a [[Command]] page will normally result in an automatically filled edit screen with separate headings for the various sections of the command definition. The extension has a database of all the command definitions from the ConTeXt distribution, and it will preload the wanted database record in the editable fields when a previously non-existing page is requested.  
  
As explained in [[Command]], some commands are instances of definitions, and pages for such commands are supposed to be redirects to the matching generator record. Guessing the matching generator record is not always easy, but the wiki search should help. All the generator records should already have their pages created, and since they all list all instances they define, it should be possible to find the 'parent' from looking at the search results.
+
As explained in [[Command]], some commands are instances of definitions, and pages for such commands are to remain as simple redirects to the matching generator record. Don't change such `<nowiki>#REDIRECT</nowiki>` pages, just save the redirect and proceed to the target page to continue editing.
  
 
== Editing XML documentation ==
 
== Editing XML documentation ==
  
First off: '''Don't Panic!''' You do not have to use XML throughout! All user-supplied documentation can use wiki code just like on the rest of the wiki pages, you just have to be a little careful about where to put it. You '''never''' have to alter the pre-generated XML.  
+
First off: '''Don't Panic!''' You do not have to use XML a lot! All user-supplied documentation can use wiki code just like on the rest of the wiki pages, you just have to be a little careful about how you key it in. You '''never''' have to alter the pre-generated XML.  
  
However, the goal of this documentation is to be easily exportable to other documentation efforts, so some care should be taken in deciding what the best way to add text. Here are some guidelines that may eventually even become enforced by the extension:
+
As the goal of this documentation is to be easily exportable to other documentation efforts, some time has been spent deciding on the best way to add documentation in a portable form. Here are some guidelines that are partially enforced by the extension:
  
* Please '''do not''' add options to or delete portions of the pre-generated XML!
 
 
* You can't use block-level objects like subsections, lists, tables and figures except in the '''Description''' and '''Examples''' sections. Most documentation fields are intended to be used as running text.
 
* You can't use block-level objects like subsections, lists, tables and figures except in the '''Description''' and '''Examples''' sections. Most documentation fields are intended to be used as running text.
* With the exception of {{tl|cmd}}, {{tl|gen}} and {{tl|todo}}, you cannot use wiki templates. Wiki templates can change over time, and that would create a nasty external dependency.
+
* With the exception of {{tl|cmd}}, {{tl|gen}}, {{tl|bug}} and {{tl|todo}}, you cannot use wiki templates. Wiki templates can change over time, and that would create a nasty external dependency.
 
* The <code>&lt;nowiki&gt;</code> tag is '''forbidden''' anywhere within a Command page.  
 
* The <code>&lt;nowiki&gt;</code> tag is '''forbidden''' anywhere within a Command page.  
 +
* As is <code>&lt;syntax&gt;</code>. Use {{tl|cmd}} or {{tl|gen}} to refer to other commands.
 
* Don't use regular HTML tags except for <code>&lt;b&gt;</code>, <code>&lt;i&gt;</code>, <code>&lt;tt&gt;</code>, <code><nowiki><pre></nowiki></code> and <code><nowiki><code></nowiki></code>.  '''As noted above:''' even the content of <code>&lt;pre&gt;</code> and <code>&lt;code&gt;</code> must be properly quoted according to the XML rules: use XML entities for less-than, greater-than and ampersand: <code>&amp;lt;</code>, <code>&amp;gt;</code> and <code>&amp;amp;</code>
 
* Don't use regular HTML tags except for <code>&lt;b&gt;</code>, <code>&lt;i&gt;</code>, <code>&lt;tt&gt;</code>, <code><nowiki><pre></nowiki></code> and <code><nowiki><code></nowiki></code>.  '''As noted above:''' even the content of <code>&lt;pre&gt;</code> and <code>&lt;code&gt;</code> must be properly quoted according to the XML rules: use XML entities for less-than, greater-than and ampersand: <code>&amp;lt;</code>, <code>&amp;gt;</code> and <code>&amp;amp;</code>
 
* You don't have to quote the XML special characters inside the text content of the <code><nowiki><texcode></nowiki></code>, <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><context></nowiki></code> tags. These three are handled as special cases to make porting existing pages easier ([[Extension:ConTeXtXML#Implementation notes]] explains this in more detail).
 
* You don't have to quote the XML special characters inside the text content of the <code><nowiki><texcode></nowiki></code>, <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><context></nowiki></code> tags. These three are handled as special cases to make porting existing pages easier ([[Extension:ConTeXtXML#Implementation notes]] explains this in more detail).
 
* You can also use the regular [http://www.mediawiki.org/wiki/Help:Formatting wikicode markup].  
 
* You can also use the regular [http://www.mediawiki.org/wiki/Help:Formatting wikicode markup].  
* Almost all inline wikicode can be used anywhere textual input is allowed (the exception is <code>&lt;nowiki&gt;</code>), and the section block wiki codes can be used in descriptions, examples, and notes.  
+
* Inline wiki code can be used almost anywhere (the exception is <code>&lt;nowiki&gt;</code> which is forbidden, and there are a few input fields are explicitly marked as 'plain text').
 +
* Section block wiki codes and  <code><nowiki><texcode></nowiki></code>, <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><context></nowiki></code> can be used in Descriptions, Examples, and Notes.  
 
* External links can be better placed in the '''See also''' section than in your main documentation.
 
* External links can be better placed in the '''See also''' section than in your main documentation.
 
* See below for a 'structural' way to refer to command parameters and options.
 
* See below for a 'structural' way to refer to command parameters and options.
Line 50: Line 50:
 
=== Editing the ''''Summary'''' ===
 
=== Editing the ''''Summary'''' ===
  
Simply finish or alter the sentence within the <code><cd:shortdesc></code> tag. The '''Summary''' should be a single sentence that gives a terse description of what the command does.  
+
Simply finish or alter the sentence. The '''Summary''' should be a single sentence that gives a terse description of what the command does.  
  
 
=== Editing the ''''Instances'''' ===
 
=== Editing the ''''Instances'''' ===
  
Some commands have a separate section with the list of predefined instances of the command. You can add some documentation into the <code><cd:constant></code> tags of this instance list, if you believe that will be useful.
+
Some commands have a separate section with the list of predefined instances of the command. You can add some documentation to go along with each of the items in this list, if you believe that will be useful.
  
 
=== Editing the ''''Settings'''' ===
 
=== Editing the ''''Settings'''' ===
Line 60: Line 60:
 
The '''Settings''' output is the Syntax table of the command or command variant, followed by a table listing the documented options. In a command with variants, there could be multiple '''Settings''' sections, with the variant name as the suffix to the title(s).
 
The '''Settings''' output is the Syntax table of the command or command variant, followed by a table listing the documented options. In a command with variants, there could be multiple '''Settings''' sections, with the variant name as the suffix to the title(s).
  
 +
Not all options to every command actually need documentation, which is why the rendered page output only shows documented options. This helps keep the wiki page size within limits and helps the user maintain general overview.
  
Not all options to every command actually need documentation, which is why the output only shows documented options. This helps keep the wiki page size within limits and helps the user maintain general overview.
+
Adding documentation for a command is done by typing wiki text into one of the supplied fields. For arguments that are keyword or assignment lists, there are multiple levels provided, so you can document the whole argument, a particular keyword or parameter, or even a particular value of a particular parameter.
 
 
Adding documentation for a command is done by typing wiki text into one of the following XML tags:
 
 
 
{|
 
| <code><cd:assignmentsdoc></code> || For documentation that applies to all key-values of a parameter option
 
|-
 
| <code><cd:paramdoc></code> || For documentation that applies to all values of a specific key-value parameter
 
|-
 
| <code><cd:keywordsdoc></code> || For documentation that applies to all values of a keyword option
 
|-
 
| <code><cd:constant></code> || For documentation that applies to a specific key-value parameter value or a specific keyword
 
|-
 
|}
 
 
 
For documentation that applies to arguments that are neither parameter nor keyword lists, you can put the documentation in the XML tag for the actual argument, for example in the <code><cd:content></code> of arguments 1 and 2 of {{cmd|doifelse}}.
 
  
 
=== Editing the ''''Description'''' ===
 
=== Editing the ''''Description'''' ===
Line 84: Line 70:
 
=== Editing the ''''Examples'''' ===
 
=== Editing the ''''Examples'''' ===
  
Each <code><cd:example></code> tag will create a level 3 heading. If you want to give it a specific title, fill in the <code>title</code> attribute. If you don't, examples will be numbered automatically as '''Example 1''', '''Example 2''', et cetera.
+
Each example will create a level 3 heading. If you want to give it a specific title, fill in the <code>Title</code> field. If you leave the title empty, examples will be numbered automatically as '''Example 1''', '''Example 2''', et cetera. You can change the example ordering on the rendered page by altering the <code>Order</code> value.  
  
 
As for '''Description''', don't forget that examples cannot be edited separately within a Command page. If it becomes unwieldy, consider editing the example in a separate scratch area like the [[Special:MyTalk]] page, then pasting the complete edited example back in.
 
As for '''Description''', don't forget that examples cannot be edited separately within a Command page. If it becomes unwieldy, consider editing the example in a separate scratch area like the [[Special:MyTalk]] page, then pasting the complete edited example back in.
Line 90: Line 76:
 
=== Editing the ''''Notes'''' ===
 
=== Editing the ''''Notes'''' ===
  
Use a <code><cd:note></code> to report something that is not quite part of the regular command reference. For example, if  you find a bug in this command in a specific ConTeXt version. You can fill in the <code>author</code> and <code>date</code> attributes manually, or use the shortcuts for signing a page:
+
Use a Note to report something that is not quite part of the regular command reference. For example, if  you find a bug in this command in a specific ConTeXt version. If you need more than one Note, you have to save the page and re-edit. That will produce a new empty note field.  
 
 
<pre>
 
<cd:note author="~~~" date="~~~~~">...</cd:note>
 
</pre>
 
 
 
That is three tildes for the author name + link, and five tildes for the timestamp).
 
  
Please do not edit other people's notes, create a new one if needed.
+
'''Note:''' notes can not be deleted, and because of that do not allow {{tl|todo}} and {{tl|bug}}
  
 
=== Editing the ''''See also'''' ===
 
=== Editing the ''''See also'''' ===
  
This section is meant for cross-references that do not need to be in the actual '''Description''' or '''Settings''' documentation. Normally, a few values are pre-filled because the cross-reference was detected while creating the database record for this command. But it is not always easy to deduct cross-references from the original interface XML, so chances are that there are many more interesting links that the database generator has missed. Feel free to add any relevant links. If you want to add an explanatory text as well, you can key that in as the XML tag content.
+
This section is meant for cross-references that do not need to be in the actual '''Description''' or '''Settings''' documentation. Normally, a few values are pre-filled because the cross-reference was detected while creating the database record for this command (some fields cannot be edited for these items).  
 
 
In case the comment containing the list of possible entries has been deleted from the record, here are the acceptable types:
 
 
 
<pre>
 
<!-- one or more of these:
 
<cd:commandref name="xx"></cd:commandref>
 
<cd:wikipage  page="xx"></cd:wikipage>
 
<cd:url        url="https://xx"></cd:url>
 
<cd:manual    pdf="xx"></cd:manual>
 
<cd:source    file="xx"></cd:source>
 
-->
 
</pre>
 
  
Fill in the <code>xx</code> with a suitable entry. Here are examples of the expected attribute values:
+
It is not always easy to automatically deduct cross-references from the original interface XML, so chances are that there are many more interesting links that the database generator has missed. Feel free to add any relevant links. If you want to add an explanatory text as well, you can key that in the final field.
  
<pre>
+
Links to wiki pages with the <code>Category:</code> or <code>Keywords:</code> prefix are automatically remapped to <code>Category:Command/</code> entries and will not appear in the visible output of the Section. This means that you cannot link to Categories other than subcategories of <code>Command/</code>; that is intentional.
<cd:commandref name="contextversion"></cd:commandref>
 
<cd:wikipage  page="Main Page"></cd:wikipage>
 
<cd:url        url="https://www.pragma-ade.com"></cd:url>
 
<cd:manual    pdf="xml-mkiv.pdf"></cd:manual>
 
<cd:source    file="cont-ini.mkiv"></cd:source>
 
</pre>
 
  
 
== Referencing ==
 
== Referencing ==
Line 130: Line 92:
 
=== Referring to outside of the current page ===
 
=== Referring to outside of the current page ===
  
You can use the normal wiki links, but it is generally better to add such links to the '''See also'' section instead.
+
You can use the normal wiki links, but it is generally better to (also) add such links to the '''See also''' section instead.
  
 
=== Referring to another section ===
 
=== Referring to another section ===
Line 157: Line 119:
 
* Outside of the '''Settings''' section, both <code>ordinal</code> and <code>variant</code> attributes are required, even if there is only one variant (<code>variant=""</code>) or one argument (<code>ordinal="1"</code>). This is because there could be a future extension to the command that would add either an argument or a variant.
 
* Outside of the '''Settings''' section, both <code>ordinal</code> and <code>variant</code> attributes are required, even if there is only one variant (<code>variant=""</code>) or one argument (<code>ordinal="1"</code>). This is because there could be a future extension to the command that would add either an argument or a variant.
  
Further, depending on what you want to show, <code>name</code> and <code>type</code> can both specified, or one of them, or both. The formatter will try to show something useful in either case.
+
Further, depending on what you want to show, <code>name</code> and <code>type</code> can both specified, or one of them, or both. The formatter will try to show something useful in either case.
 
 
''A warning'': During preview, <code><cd:iref/></code> will not be able to access data from outside of the current section you are editing. This will (barring errors) resolve itself once the section is saved and the full page is reloaded.
 

Latest revision as of 18:15, 29 August 2020

Common problems

Normally, a page like this would start with a simple introduction and hide the issues at the bottom. But if you are not familiar with editing XML and/or how the Command setup works, you are very likely to see errors before you have read the rest of this page. So here we go:

  • I tried to create a new page but the form shows an error immediately.
You tried to create a page for a ConTeXt command that is not documented in the interface files. Check that you didn't make a typing error first. If this is not the case or you are unsure, ask for advice on the mailing list.
  • When saving my edit, I see some red text with an XML error.
Internally, Command pages must be either well-formed XML, or nothing but a #REDIRECT. You likely made a booboo with an XML tag or have an unquoted < or & somewhere. Only the content of <xmlcode>, <texcode>, and <context> are exempt from the normal XML rules (but on the downside, they cannot be nested). You will need to properly quote any attribute values, though. And note that <pre> and <code> content should be properly quoted as well.
  • After preview, when saving my edit, I see some red text with an XML error about a stray < or &.
Because of the special handling of <xmlcode>, <texcode>, and <context>, sometimes the preview resolves entity references outside of <xmlcode>, <texcode>, and <context> into their replacement. Sorry, you will have to go through again and replace the indicated <'s and &'s back to an entity reference (this is a bug, but it is one that is very hard to fix). If all else fails: use <lt/> and <amp/> instead of XML entities.
  • I get a warning that the revision is outdated.
This happens when the command definition has been updated externally, for example after a new ConTeXt distribution has been installed on the server. The warning should be harmless (this warning is likely to be removed in the future)
  • The preview does not show my edit properly.
Command pages must resolve into well-formed XML. Try to save your edit, and you will almost certainly see a XML error that is preventing the preview from working properly.

Introduction

The pages under Command are managed by a plugin that saves the page body either as an XML interface documentation record or as a redirect. So, a page under control of the plugin:

  • is an XML snippet with the <cd:commandgroup> top-level tag,
  • or a #REDIRECT to another page.

For the redirect case, you will see the standard wiki edit dialog. For the XML case, a dedicated form is provided with sections that can be hidden / shown by clicking on the form section title.

The documentation inside the XML form can make use of (some) wiki markup, as explained below.

Starting to edit a Command page will normally result in an automatically filled edit screen with separate headings for the various sections of the command definition. The extension has a database of all the command definitions from the ConTeXt distribution, and it will preload the wanted database record in the editable fields when a previously non-existing page is requested.

As explained in Command, some commands are instances of definitions, and pages for such commands are to remain as simple redirects to the matching generator record. Don't change such #REDIRECT pages, just save the redirect and proceed to the target page to continue editing.

Editing XML documentation

First off: Don't Panic! You do not have to use XML a lot! All user-supplied documentation can use wiki code just like on the rest of the wiki pages, you just have to be a little careful about how you key it in. You never have to alter the pre-generated XML.

As the goal of this documentation is to be easily exportable to other documentation efforts, some time has been spent deciding on the best way to add documentation in a portable form. Here are some guidelines that are partially enforced by the extension:

  • You can't use block-level objects like subsections, lists, tables and figures except in the Description and Examples sections. Most documentation fields are intended to be used as running text.
  • With the exception of {{cmd}}, {{gen}}, {{bug}} and {{todo}}, you cannot use wiki templates. Wiki templates can change over time, and that would create a nasty external dependency.
  • The <nowiki> tag is forbidden anywhere within a Command page.
  • As is <syntax>. Use {{cmd}} or {{gen}} to refer to other commands.
  • Don't use regular HTML tags except for <b>, <i>, <tt>, <pre> and <code>. As noted above: even the content of <pre> and <code> must be properly quoted according to the XML rules: use XML entities for less-than, greater-than and ampersand: &lt;, &gt; and &amp;
  • You don't have to quote the XML special characters inside the text content of the <texcode>, <xmlcode>, and <context> tags. These three are handled as special cases to make porting existing pages easier (Extension:ConTeXtXML#Implementation notes explains this in more detail).
  • You can also use the regular wikicode markup.
  • Inline wiki code can be used almost anywhere (the exception is <nowiki> which is forbidden, and there are a few input fields are explicitly marked as 'plain text').
  • Section block wiki codes and <texcode>, <xmlcode>, and <context> can be used in Descriptions, Examples, and Notes.
  • External links can be better placed in the See also section than in your main documentation.
  • See below for a 'structural' way to refer to command parameters and options.

Editing the 'Summary'

Simply finish or alter the sentence. The Summary should be a single sentence that gives a terse description of what the command does.

Editing the 'Instances'

Some commands have a separate section with the list of predefined instances of the command. You can add some documentation to go along with each of the items in this list, if you believe that will be useful.

Editing the 'Settings'

The Settings output is the Syntax table of the command or command variant, followed by a table listing the documented options. In a command with variants, there could be multiple Settings sections, with the variant name as the suffix to the title(s).

Not all options to every command actually need documentation, which is why the rendered page output only shows documented options. This helps keep the wiki page size within limits and helps the user maintain general overview.

Adding documentation for a command is done by typing wiki text into one of the supplied fields. For arguments that are keyword or assignment lists, there are multiple levels provided, so you can document the whole argument, a particular keyword or parameter, or even a particular value of a particular parameter.

Editing the 'Description'

Arguably the most important section for a command reference. If you want to put a heading in remember to start at level three (===) and don't forget that such sections cannot be edited separately within a Command page. If it becomes unwieldy, consider editing the text in a separate scratch area like the Special:MyTalk page, then pasting the complete edited text back in.

Editing the 'Examples'

Each example will create a level 3 heading. If you want to give it a specific title, fill in the Title field. If you leave the title empty, examples will be numbered automatically as Example 1, Example 2, et cetera. You can change the example ordering on the rendered page by altering the Order value.

As for Description, don't forget that examples cannot be edited separately within a Command page. If it becomes unwieldy, consider editing the example in a separate scratch area like the Special:MyTalk page, then pasting the complete edited example back in.

Editing the 'Notes'

Use a Note to report something that is not quite part of the regular command reference. For example, if you find a bug in this command in a specific ConTeXt version. If you need more than one Note, you have to save the page and re-edit. That will produce a new empty note field.

Note: notes can not be deleted, and because of that do not allow {{todo}} and {{bug}}

Editing the 'See also'

This section is meant for cross-references that do not need to be in the actual Description or Settings documentation. Normally, a few values are pre-filled because the cross-reference was detected while creating the database record for this command (some fields cannot be edited for these items).

It is not always easy to automatically deduct cross-references from the original interface XML, so chances are that there are many more interesting links that the database generator has missed. Feel free to add any relevant links. If you want to add an explanatory text as well, you can key that in the final field.

Links to wiki pages with the Category: or Keywords: prefix are automatically remapped to Category:Command/ entries and will not appear in the visible output of the Section. This means that you cannot link to Categories other than subcategories of Command/; that is intentional.

Referencing

Referring to outside of the current page

You can use the normal wiki links, but it is generally better to (also) add such links to the See also section instead.

Referring to another section

Simply use the normal Wiki syntax for internal links, e.g. #Introduction.

Referring to an argument, option or value

While writing documentation, it is often necessary to refer to a specific option or parameter. For this purpose, there is one extra XML element that can be used within the Command documentation.

The XML tag <cd:iref/> defines an empty element that can be used to reference specific arguments, parameters, or even parameter values from anywhere within the documentation. It accepts up to four attributes:

variant the name of a variant, as given in the variant attribute of the <cd:command> tag. If the XML attribute is missing from <cd:command> but there are multiple variants, then use variant="".
ordinal the ordinal number of a command argument, as in the ordinal attribute of the relevant argument tag
name the name of a parameter in a key-value command (the value of a name attribute of a <cd:parameter>)
type the value of a parameter in a key-value command, or a keyword. (the value of a type attribute on a <cd:constant> )
  • When inside of a command argument's substructure, if you are referring to something within the same argument, then ordinal is optional.
  • Similarly, when inside of a variant command and referring to something within the same variant, then the variant is optional.
  • Outside of the Settings section, both ordinal and variant attributes are required, even if there is only one variant (variant="") or one argument (ordinal="1"). This is because there could be a future extension to the command that would add either an argument or a variant.

Further, depending on what you want to show, name and type can both specified, or one of them, or both. The formatter will try to show something useful in either case.