3,897
edits
Changes
Jump to navigation
Jump to search
However, As the goal of this documentation is to be easily exportable to other documentation efforts, so some care should be taken in deciding what the best way is to add text. Here are some guidelines that may eventually even become enforced by the extension:
* Please '''do not''' add options to or delete portions of the pre-generated XML!
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.
That is three tildes for the author name + link, and five tildes for the timestamp)'''Note:''' notes can not be deleted.
Please do not edit other people's notes, create a new one if needed.
In case the comment containing the list of possible entries has been deleted It is not always easy to automatically deduct cross-references from the recordoriginal interface XML, here so chances are the acceptable types: <pre><!-- one or that there are many 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 in interesting links that the <code>xx</code> with a suitable entrydatabase generator has missed. Here are examples of Feel free to add any relevant links. If you want to add an explanatory text as well, you can key that in the expected attribute values: <pre><cd:commandref name="contextversion"></cd:commandref><cd:wikipage page="Main Page"></cd:wikipage><cd:url url="https://www.pragma-ade.com"></cd:url><cd:manual pdf="xml-mkiv.pdf"></cd:manual><cd:source file="cont-inifinal field.mkiv"></cd:source></pre>
no edit summary
{{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)}}
== Common problems ==
Normally, a page like this would start with a simple introduction and hide the issues at the bottom. But if you are not familiar with editing XML and/or how the [[Command]] setup works, you are very likely to see errors before you have read the rest of this page. So here we go:
* '''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 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 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 `>` 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 attributes, though. And note that <nowiki><pre></nowiki> and <nowiki><code></nowiki> content should be properly quoted as well.* '''I tried to When saving my edit a sectionafter preview, but I see some red text with an XML error that says 'Section not found'.''': Only Because of the special handling of `<nowiki><xmlcode></nowiki>`, `<nowiki><texcode></nowiki>`, and `<nowiki><context></nowiki>`, sometimes the preview changes entity references back into their meaning. Sorry, you will have to go through again and replace the predefined top-level sections can be edited separately (this limitation is likely indicated `<` or `&` back to stay)an entity reference.
* '''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 documentation inside the XML tree can make use of (some) wiki markup, as explained below.
Editing 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 redirects to the matching generator record. Don't change such `<nowiki>#REDIRECT</nowiki>` pages, just go save the redirect and proceed to the target page to continueediting.
== Editing XML documentation ==
First off: '''Don't Panic!''' You do not have to use XML throughout! 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 how to put key itin. You '''never''' have to alter the pre-generated XML.
* 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}} and {{tl|todo}}, you cannot use wiki templates. Wiki templates can change over time, and that would create a nasty external dependency.
=== 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 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.
=== 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).
Not all options to every command actually need documentation, which is why the rendered page output only shows documented options. This helps keep the wiki page size within limits and helps the user maintain general overview.
=== Editing the ''''Description'''' ===
=== 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>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.
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> 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 If you need more than one Note, you have to save the <code>author</code> page and <code>date</code> attributes manually, or use the shortcuts for signing re-edit. That will produce a page: <pre><cd:new empty note author="~~~" date="~~~~~">field...</cd:note></pre>
=== 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(some fields cannot be edited for these items).
== 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 ===
* 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>). 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'': 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.
