3,897
edits
Changes
Jump to navigation
Jump to search
{{todo|Once again, this page has been updated based on a future situation. But you should not have to wait too long, and a new edit form for Command pages is coming soon.
[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 21:08, 25 August 2020 (CEST)}}
Editing 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.
→Editing the 'Notes'
== Common problems ==
* '''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.'''
: 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 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). 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.'''
: 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. 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.
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.
* 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><nowiki></code> tag is '''forbidden''' anywhere within a Command page.
* As is <code><syntax></code>. Use {{tl|cmd}} or {{tl|gen}} to refer to other commands.
* Don't use regular HTML tags except for <code><b></code>, <code><i></code>, <code><tt></code>, <code><nowiki><pre></nowiki></code> and <code><nowiki><code></nowiki></code>. '''As noted above:''' even the content of <code><pre></code> and <code><code></code> must be properly quoted according to the XML rules: use XML entities for less-than, greater-than and ampersand: <code>&lt;</code>, <code>&gt;</code> and <code>&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 can also use the regular [http://www.mediawiki.org/wiki/Help:Formatting wikicode markup].
* Almost all inline wikicode Inline 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 and <code><nowiki><texcode></nowiki></code>, <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><context></nowiki></code> 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.
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 {{tl|todo}} and {{tl|bug}}
=== Editing the ''''See also'''' ===
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 <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.
== 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 ===
