3,897
edits
Changes
Jump to navigation
Jump to search
The documentation inside For the redirect case, you will see the standard wiki edit dialog. For the XML tree case, a dedicated form is provided with sections that can make use of (some) wiki markup, as explained belowbe hidden / shown by clicking on the form section title.
Editing a [[Command]] page will normally result in an automatically filled edit screen with separate headings for the various sections of The documentation inside the command definition. The extension has a database XML form can make use of all the command definitions from the ConTeXt distribution(some) wiki markup, and it will preload the wanted database record in the editable fields when a previously non-existing page is requestedas explained below.
no edit summary
* '''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 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.
* '''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 `&` 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 attributesattribute values, though. And note that <nowiki><pre></nowiki> and <nowiki><code></nowiki> content should be properly quoted as well.* '''When After preview, when saving my edit after preview, I see some red text with an XML errorabout a stray `<` or `&`.''': Because of the special handling of `<nowiki><xmlcode></nowiki>`, `<nowiki><texcode></nowiki>`, and `<nowiki><context></nowiki>`, sometimes the preview changes resolves entity references back outside of `<nowiki><xmlcode></nowiki>`, `<nowiki><texcode></nowiki>`, and `<nowiki><context></nowiki>` into their meaningreplacement. Sorry, you will have to go through again and replace the indicated `<` or 's and `&` 's back to an entity reference(this is a bug, but it is one that is very hard to fix).* '''I get a warning that the revision is outdated at the top of the edit screen.'''
: 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 be either resolve into well-formed XML. Try to save your edit, and you will almost certainly see a XML errorthat 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:
* 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.
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 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 ==
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 how to 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, so some care should be taken in time has been spent deciding what on the best way is to add textdocumentation in a portable form. Here are some guidelines that may eventually even become 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.
* 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].
* Almost all inline wikicode wiki code can be used almost anywhere textual input is allowed (the exception is <code><nowiki></code>)which is forbidden, and the section there are a few input fields are explicitly marked as 'plain text'). * Section block wiki codes can be used in descriptionsDescriptions, examplesExamples, and notesNotes.
* 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.
