3,899
edits
Changes
Jump to navigation
Jump to search
start of explanation of the new /Command subsystem
{{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.
--[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 20:45, 9 August 2020 (CEST)}}
== 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 [[source:tex/context/interface/mkiv |interface xml files]] in the ConTeXt distribution ([[#Pre-existing pages |see below]] for legacy pages).
The new pages are controlled by the [[Extension:ConTeXtXML | 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 [[Extension:ConTeXtXML | 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` ({{cmd|setuphead}}).
=== Environments ===
Environments like `\starttext ... \stoptext` have a page based on the starting command: `/Command/starttext` ({{cmd|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 {{cmd|startchapter}}, which is defined using {{cmd|definesection|[chapter]}}, and {{cmd|startitemize}}, which is defined using {{cmd|defineitemgroup|[itemize]}}.
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}}).
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}}.
== Page stucture ==
The structure of the new command pages is always the same:
{|
|-
|style="width: 20%"| '''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 [[Extension:ConTeXtXML | 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). <br/>Do '''not''' leave a redirect.
* Now go to the `/Command/setuphead` url.<br/>If you followed a wiki link, it should automatically open the editor. Otherwise, click on the `Create` link.<br/>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)
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.
--[[User:Taco|Taco]] ([[User talk:Taco|talk]]) 20:45, 9 August 2020 (CEST)}}
== 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 [[source:tex/context/interface/mkiv |interface xml files]] in the ConTeXt distribution ([[#Pre-existing pages |see below]] for legacy pages).
The new pages are controlled by the [[Extension:ConTeXtXML | 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 [[Extension:ConTeXtXML | 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` ({{cmd|setuphead}}).
=== Environments ===
Environments like `\starttext ... \stoptext` have a page based on the starting command: `/Command/starttext` ({{cmd|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 {{cmd|startchapter}}, which is defined using {{cmd|definesection|[chapter]}}, and {{cmd|startitemize}}, which is defined using {{cmd|defineitemgroup|[itemize]}}.
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}}).
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}}.
== Page stucture ==
The structure of the new command pages is always the same:
{|
|-
|style="width: 20%"| '''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 [[Extension:ConTeXtXML | 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). <br/>Do '''not''' leave a redirect.
* Now go to the `/Command/setuphead` url.<br/>If you followed a wiki link, it should automatically open the editor. Otherwise, click on the `Create` link.<br/>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)
