3,897
edits
Changes
Jump to navigation
Jump to search
that should be it, I hope
* See below for a 'structural' way to refer to command parameters and options.
=== 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.
=== 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.
=== 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).
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'''' ===
Arguably the most important section for a command reference. If you want to put a heading in remember to start at level three (<code>===</code>) 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 <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.
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 <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:
Please do not edit other people's notes, create a new one if needed.
=== 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.
</pre>
== Referencing == === 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. === Referring to another section === Simply use the normal Wiki syntax for internal links, e.g. <code>[[#Introduction]]</code>. === 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 <code><cd:iref/></code> 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: {{todo|more later |-| <code>variant</code> || the name of a variant, as given in the <code><cd:command></code> tag. If the tag is missing from <code><cd:command></code> but there are multiple variants, then use <code>variant=""</code>.|-| <code>ordinal</code> || the ordinal number of a command argument, as in the <code>ordinal</code> attribute of the relevant argument tag|-| <code>name</code> || the name of a parameter in a key-[[Uservalue command (the value of a <code>name</code> attribute of a <code><cd:Tacoparameter></code>)|Taco]] -| <code>type</code> || the value of a parameter in a key-value command, or a keyword. ([[User talkthe value of a <code>type</code> attribute on a <code><cd:Tacoconstant></code> )|talk]]} * When inside of a command argument's substructure, if you are referring to something within the same argument, then <code>ordinal</code> is optional. * Similarly, when inside of a variant command and referring to something within the same variant, then the <code>variant</code> is optional.* 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>) 15. 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. ''A warning'':34During preview, 10 August 2020 <code><cd:iref/></code> will not be able to access data from outside of the current section you are editing. This will (CESTbarring errors)}}resolve itself once the section is saved and the full page is reloaded.
