51
edits
Changes
Jump to navigation
Jump to search
Moved the prototype to a separate repo for reference; updated links
I've put together a hand0built prototype with a handful of commands to act as examples:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype
=== Topic Level Features ===
One of the first elements in a topic is the `shortdesc` element:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/3ce40bd9cf687d549afae2ac9928f7b0f7b90e67master/en/commands/b/r_command_blank.dita#L5-L7
This element holds a brief description of the topic.
The metadata for the topic is contained in the `prolog` element:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/b/r_command_blank.dita#L8-L19
We have a few interesting features here.
The main body of the topic (the `refbody` element) starts with a discussion of syntax:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/v/r_command_vspacing.dita#L20-L39
This includes a description of the syntax phrase, as well as a table of all of the arguments, with a quick description of each.
Example:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/v/r_command_vspacing.dita#L40L20-L250L39
If the command accepts options (single keywords, identified as 'keyword' in the interface files) as part of its setups, they are presented in a table in the body of the topic. The options table presents each option, and a brief description of what it does. The options section also can support notes, more tables, etc.
Commands can inherit option content from other topics, as in:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/b/r_command_blank.dita#L50-L53 When the final document is produced, this inheritance directive will copy the source content into the topic, so it's available to users in both places immediately.
==== Settings ====
Example:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/s/r_command_setupbuffer.dita#L47-L118
If the commands accepts settings (key-value pairs, identified as 'parameter' in the interface files) as part of its setups, they are presented as a grouped series of tables in the body of the topic; each key has a table of available values for the key and their descriptions.
Commands can inherit sets of settings content from other topics, as in:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/d/r_command_definebuffer.dita#L58-L71
Commands can also inherit an option set as the values of a setting key:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/s/r_command_setuptyping.dita#L660-L664 When the final document is produced, this inheritance directive will copy the source content into the topic, so it's available to users in both places immediately.
==== Notes ====
A notes `section` can be included:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/v/r_command_vspacing.dita#L251-L345
Individual notes can be included in various sections with the `note` element: use of a notes section can also be useful for general documentation that doesn't fit elsewhere in the topic.
A goal is to have one minimal working example for every command. For example:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/b/r_command_bold.dita#L43-L52
It's fairly straightforward to pull the MWE out of the topic; one piece of future work is adding automatic builds of MWEs back into the manual as image assets, if requested in the topic (using the 'otherprops' attribute). To be reasonable, this should be handled entirely automatically by the build system.
For this document set, the relationships are described with a `reltable` in the relations map:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/master/en/relations.ditamap
This allows for arbitrary relationships between commands, and the relationships can be ignored if the commands aren't included in a given product, surpassing confusing and/or broken links in the output.
Each command topic can also have an explicit related links section:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/e47c6b649db410d030301427b3e8583770333e67936e331726515175160190a6b383f7735105c8cb/en/commands/i/r_command_input.dita#L65-L69
This can also be used to pointing the user at some other external, relevant part of the ConTeXt documentation system (a manual, or a My Way, etc.).
The topics themselves know nothing about the hierarchy into which they're placed for a product; this is handled with a ditamap file, which establishes inclusion, hierarchy, order, and grouping:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/master/en/context_command_reference.ditamap
Map files can link to other map files helping reduce the complexity of maintenance.
A core part of how DITA transforms and transcodes content from topic to topic is through the use of keys; DITA uses these (arbitrary) labels to know where to find specific pieces of content. These keys are maintained in their own map:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/master/en/inheritance.ditamap
==== Using a Map to Establish Relationships Between Topics ====
For this document set, the relationships are described with a `reltable` in the relations map:
https://github.com/pmazaitis/context_command_referencecontext_command_reference_prototype/blob/master/en/relations.ditamap
This is a simple two column table that describes commands (column one) and the commands related to that command (column two).
