Difference between revisions of "Command"

From Wiki
Jump to navigation Jump to search
(start of explanation of the new /Command subsystem)
 
Line 29: Line 29:
 
In the xml documentation generated commands like {{cmd|startchapter}} and {{cmd|startsubject}} are grouped together, because all commands generated by {{cmd|definesection}} have the exact same parameters and options.
 
In the xml documentation generated commands like {{cmd|startchapter}} and {{cmd|startsubject}} are grouped together, because all commands generated by {{cmd|definesection}} have the exact same parameters and options.
  
To mimic this on the wiki, for generated commands there is a single page for the group. For such pages, the page name starts with an underscore. For the sectioning example, that is `/Command/_startsection`. There are also the pages `/Command/startchapter` ({{cmd|startchapter}}) and `/Command/startsubject` ({{cmd|startsubject}}), but these are just redirect pages to `/Command/_startsection` ({{cmd|_startsection}}).
+
To mimic this on the wiki, for generated commands there is a single page for the group. For such pages, the page name starts with an underscore. For the sectioning example, that is `/Command/_startsection`. There are also the pages `/Command/startchapter` ({{cmd|startchapter}}) and `/Command/startsubject` ({{cmd|startsubject}}), but these are intended to be redirect pages to `/Command/_startsection` ({{cmd|_startsection}}).
  
 
As you can see above, Using the {{tl|cmd}} template for referring to the group pages looks a bit weird (`<nowiki>{{cmd|_startsection}}</nowiki>` was given) which is why there is a separate template for referring to those group pages: {{tl|gen}}. `<nowiki>{{gen|startsection}}</nowiki>` produces: {{gen|startsection}}.
 
As you can see above, Using the {{tl|cmd}} template for referring to the group pages looks a bit weird (`<nowiki>{{cmd|_startsection}}</nowiki>` was given) which is why there is a separate template for referring to those group pages: {{tl|gen}}. `<nowiki>{{gen|startsection}}</nowiki>` produces: {{gen|startsection}}.

Revision as of 10:12, 13 August 2020


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) 20:45, 9 August 2020 (CEST) (See: To-Do List)


ConTeXt command reference

Newly created ConTeXt command reference pages (pages with prefix /Command in their title) are a little different from all other pages on this wiki. They look like normal wiki pages when viewing, but the source is in fact an XML file that is derived from the interface xml files in the ConTeXt distribution (see below for legacy pages).

The new pages are controlled by the ConTeXtXML wiki extension. The extension takes care of the conversion from XML to HTML for viewing, and will automatically update the page source if there are some changes in the command definition in the ConTeXt distribution. Also, it stores the page in XML format on the harddisk of the server, so that it can be used in other documentation efforts like a proper reference manual. More details about how that all works can be found in the ConTeXtXML extension page.

As a result of the extra management layer and the XML format, some extra care is needed when editing the /Command pages, and that is explained in Help:Command.

About page names

Simple commands

Simple commands like \setuphead have a simple page name as well: /Command/setuphead (\setuphead).

Environments

Environments like \starttext ... \stoptext have a page based on the starting command: /Command/starttext (\starttext).

Generated commands and environments

In ConTeXt, some commands and environments are created by use of another command, typically a command whose name starts with \define.... Users are free to define their own commands and environments that way, but some such are in fact predefined by ConTeXt itself. Examples are \startchapter, which is defined using \definesection[chapter], and \startitemize, which is defined using \defineitemgroup[itemize].

In the xml documentation generated commands like \startchapter and \startsubject are grouped together, because all commands generated by \definesection have the exact same parameters and options.

To mimic this on the wiki, for generated commands there is a single page for the group. For such pages, the page name starts with an underscore. For the sectioning example, that is /Command/_startsection. There are also the pages /Command/startchapter (\startchapter) and /Command/startsubject (\startsubject), but these are intended to be redirect pages to /Command/_startsection (\_startsection).

As you can see above, Using the {{cmd}} template for referring to the group pages looks a bit weird ({{cmd|_startsection}} was given) which is why there is a separate template for referring to those group pages: {{gen}}. {{gen|startsection}} produces: startsection.

Page stucture

The structure of the new command pages is always the same:

Table of Contents All Command pages have a toc.
Command title Nicely formatted title.
Summary A short line explaining the command's use.
Instances Only for grouped pages. If there are any predefined instances, they are listed in a table here.
Settings The syntax table, and the documentation for various options and arguments right below. This section may be repeated in cases where a command has different ways of using it.
Description The main documentation of the command.
Examples Examples, each one in a separate subheading.
Notes Any special notes, like 'available since XXXX'.
See also Links to other relevant places.
Forum help A list of quick-links to community searches.

Pre-existing pages

The behaviour of pages that were already in existence before the ConTeXtXML extension took over management does not change. They can still be edited as normal wiki pages.

We of course want such pages to be converted into the new format. The recipe for that is:

  • Move the existing page away to e.g. /Command_old/setuphead (this can be done via the More dropdown at the top of the page).
    Do not leave a redirect.
  • Now go to the /Command/setuphead url.
    If you followed a wiki link, it should automatically open the editor. Otherwise, click on the Create link.
    The edit screen will automatically be filled with an XML template that is suitable for the command you are editing (if the Edit field remains empty, you are trying to document a no longer existing command, or a command that is generated, as explained above)
  • Open /Command_old/setuphead in a different browser window, and copy the documentation therein into the proper spots of the new /Command/setuphead page.
  • Save the new /Command/setuphead, and delete the /Command_old/setuphead page (this can also be done via the More dropdown at the top of the page)