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)}}
* Outside of <code><nowiki><texcode></nowiki></code>, <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><context></nowiki></code>, it may be better to use <code><nowiki><amp/></nowiki></code> and <code><nowiki><lt/></nowiki></code> instead of XML entities to prevent problems with the Edit Preview functionality.
→Editing the 'Notes'
== Common problems ==
: 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 `<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.
* '''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 `<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). Or betterIf all else fails: use `<nowiki><lt/></nowiki>` and `<nowiki><amp/></nowiki>` 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)
* 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 Inline wiki code can be used almost anywhere(the exception is <code><nowiki></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.
* 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 ==
