3,897
edits
Changes
Jump to navigation
Jump to search
== Implementation notes ==
=== About those extension tags ===
The special tags <code><nowiki><texcode></nowiki></code>, <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><context></nowiki></code> on our wiki are handled by an extension (<code>context</code>) written a long time ago by Patrick Gundlach. That extension converts the parsed XML output from mediawiki into HTML code that looks 'right'. In normal wiki pages this works, because the mediawiki XML parser is quite forgiving and does some recovery attempts itself when a user keys in something that is not quite well-formed XML.
For example, in a normal wiki page you do not need to properly quote the attributes of <code><nowiki><context></nowiki></code>. And the structure within <code><nowiki><xmlcode></nowiki></code> does not have to be properly nested.
But it also sometimes backfires. If you use a XML tag name inside a <code><nowiki><context source="yes"></nowiki></code> call or <code><nowiki><texcode></nowiki></code>, it will not be displayed in the verbatim text section (but it will be seen by ConTeXt while processing the <code><nowiki><context></nowiki></code>).
To solve this problem between 'it is data' and 'it is markup' in a standalone XML file, you would wrap a CDATA section around things like the content of <code><nowiki><xmlcode></nowiki></code>. But unfortunately that is something that either the mediawiki parser or the <code>context</code> does not understand (I don't know which is the exact problem).
For now, I decided to treat the content of <code><nowiki><texcode></nowiki></code>, <code><nowiki><xmlcode></nowiki></code>, and <code><nowiki><context></nowiki></code> as if they are SGML elements with data model CDATA. That means that the generated XML files on disk are not actually well-formed, for example this content of <code><nowiki><xmlcode></nowiki></code>:
<xmlcode>
<document>
This <highlight detail="important">you</highlight> need to know.
</document>
</xmlcode>
should actually be this:
<xmlcode><![CDATA[
<document>
This <highlight detail="important">you</highlight> need to know.
</document>
]]></xmlcode>
but then it could either not be displayed on the wiki, or (with some internal patching) there would be a constant difference between the XML version on disk and the wiki database version of a page (resulting in endless 'This revision is outdated' messages). So, I think this is the best solution for now.
implementation notes moved
: 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). Note 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 edit a section, but I see an error that says 'Section not found'.'''
: Only the predefined top-level sections can be edited separately (this limitation is likely to stay).
* The <code><nowiki></code> tag is '''forbidden''' anywhere within a Command page.
* 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 can be used anywhere textual input is allowed (the exception is <code><nowiki></code>), and the section block wiki codes can be used in descriptions, examples, and notes.
''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.
