Changes

* '''I tried to create a new page but the form loads up emptyshows 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 If this 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 not the case or you are unsure, ask for advice on the mailing list.

: 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 `>` 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). Note 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: the wikicode tag is not the same as the actual HTML tag, even though its results are visually similar.* '''I tried to After preview, when saving my edit a section, but I see some red text with an XML error that says 'Section not found'about a stray `<` or `&`.''': Only 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 predefined top-level sections can be edited separately indicated `<`'s and `&`'s back to an entity reference (this limitation is likely a bug, but it is one that is very hard to stayfix). 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.'''

* should be is an XML snippet with the `<cd:commandgroup>` top-level tag. ,* or a single line with 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 form can make use of (some) wiki markup, as explained below.

Editing Starting to edit a [[Command]] page will normally result in an automatically filled edit screenwith 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 Edit field 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 remain as simple redirects to the matching generator record. Guessing the matching generator record is not always easyDon't change such `<nowiki>#REDIRECT</nowiki>` pages, but the wiki search should help. All just save the generator records should already have their pages created, redirect and since they all list all instances they define, it should be possible proceed to find the 'parent' from looking at the search resultstarget page to continue editing.

First off: '''Don't Panic!''' You do not have to use XML throughouta 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 where to put how you key itin. You '''never''' have to alter the pre-generated XML.

However, As the goal of this documentation is to be easily exportable to other documentation efforts, so some care should be taken in time has been spent deciding what on the best way to add textdocumentation in a portable form. Here are some guidelines that may eventually even become are partially enforced by the extension:

* Please You can'''do not''' add options to or delete portions of the pre-generated XML!* Do not 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}}, {{tl|bug}} and {{tl|todo}}, do not you cannot use wiki templates. Wiki templates can change over time, and that creates would create a nasty external dependency, so they are disallowed.* 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> (but 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> is usually a better choice) , <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><codecontext></nowiki></code>tags. For bold or italic text, 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]. Most inline wikicode * Inline wiki code can be used almost anywhere, and (the sectioning codes can be used in descriptions, examples, and notes. The one exception is `<code>&lt;nowiki&gt;</code>`, that which is forbidden everywhere, and there are a few input fields are explicitly marked as 'plain text'). As noted above, the content of * Section block wiki codes and <code><nowiki><pretexcode></nowiki></code> and , <code><nowiki><codexmlcode></nowiki></code> must be properly quoted according to the XML rules: use XML entities for less-than, greater-than and ampersand: <code>&amp;lt;</codenowiki>, <codecontext>&amp;gt;</code> and <codenowiki>&amp;amp;</code>can be used in Descriptions, Examples, and Notes.

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.

Some commands have a separate section with the list of predefined instances of the command. You can add some documentation into to go along with each of the <code><cd:constant></code> tags of items in this instance list, if you believe that will be useful.

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 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|- |} supplied fields. For documentation that applies to arguments that are neither parameter nor keyword or assignment lists, there are multiple levels provided, so you can put the documentation in the XML tag for document the actual whole argument, for example in the <code><cd:content></code> a particular keyword or parameter, or even a particular value of arguments 1 and 2 of {{cmd|doifelse}}a particular parameter.

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>titleTitle</code> attributefield. If you don'tleave 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.

Use a <code><cd:note></code> 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. You can fill in the <code>author</code> and <code>date</code> attributes manuallyIf you need more than one Note, or use you have to save the shortcuts for signing a page: <pre><cd:note author="~~~" date="~~~~~">and re-edit...</cd:That will produce a new empty note></pre> That is three tildes for the author name + link, and five tildes for the timestamp)field.

Please do not edit other people's ''Note:''' notescan not be deleted, create a new one if needed.and because of that do not allow {{tl|todo}} and {{tl|bug}}

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). 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. 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 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 <code>xx</code> with a suitable entryfinal field. Here are examples of the expected attribute values:

Links to wiki pages with the <precode><cdCategory:commandref name="contextversion"></cd:commandrefcode>or <cdcode>Keywords:wikipage page="Main Page"></cd:wikipagecode>prefix are automatically remapped to <cd:url url="httpscode>Category:Command//www.pragma-ade.com"></cd:urlcode><cd:manual pdf="xml-mkiventries and will not appear in the visible output of the Section.pdf">This means that you cannot link to Categories other than subcategories of </cd:manualcode><cd:source file="cont-ini.mkiv"><Command/cd:source></precode>; that is intentional.

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

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.