Help:Command

From Wiki
Revision as of 12:07, 10 August 2020 by Taco (talk | contribs)
Jump to navigation Jump to search

TODO: This page documents the situation that will become active in a few days/a week when a newly developed wiki extension will be ported over from the test wiki. This page is written in preparation. Soon, this todo block will be deleted.

We have a heatwave right now, and even though there are some things in the extension that I still want to improve on, it is too hot in the actual office to do any programming. Instead, I am on the couch in front of a fan.

--Taco (talk) 22:52, 9 August 2020 (CEST) (See: To-Do List)


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 empty.
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 #REDIRECT. If neither are the case of 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 #REDIRECT. You likely made a booboo with an XML tag.
  • 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).
  • 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)

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 XML with the <cd:commandgroup> top-level tag.
  • or a single line with a #REDIRECT to another page

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 screen. 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 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. Guessing the matching generator record is not always easy, but the wiki search should help. All the generator records should already have their pages created, and since they all list all instances they define, it should be possible to find the 'parent' from looking at the search results.

Editing XML documentation

First off: Don't Panic! You do not have to use XML throughout! All user-supplied documentation can use wikicode just like on the rest of the wiki. You just have to be careful about where to put it. You never have to edit the pre-generated XML.

However, 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 to add text. Here are some guidelines that may eventually even become enforced by the extension:

  • Do not 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 {{cmd}}, {{gen}} and {{todo}}, do not use wiki templates. Wiki templates can change over time, and that creates a nasty external dependency.
  • Don't use regular HTML tags except for <pre> (but <texcode> is usually a better choice) and <code> (but backticks also work for that). For bold or italic text, use the regular wikicode markup.
  • 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.

TODO: to be finished later --Taco (talk) 22:52, 9 August 2020 (CEST) (See: To-Do List)