51
edits
Changes
Jump to navigation
Jump to search
- * user: command is meant for the general ConTeXt user base- * programmer: command is meant for folks who create their own ConTeXt commands- * implementor: command is meant for internal use in ConTeXt development
From At the hand-built prototypemoment, The DITA Open Toolkit (dita-ot) can generate lots the distribution supports three maps of different formats out of the box, and use plugins for others. Here are some examples, all generated from the above DITA document set.command topics:
=== HTML5 ===* The full command set* User-facing commands* System commands
`dita-ot` can generate an HTML version ...each drawing on the same pool of command topics to build the documentation set: final product.
`dita --input=context_command_reference.ditamap --format=html5` ...as hosted here: https://paul.mazaitis.org/ctx_comref/html5/ This is without any CSSMaps could also be made to support command glossaries for manuals, etc. - just the structure. === XSL-FO PDF === `dita-ot` can generate an XSL-FO version of the documentation set:
dita --input=context_command_reference.ditamap --format=pdf
...as hosted here:==== Keeping Track of What Needs To Be Worked On ====
https://paulSeveral elements in the topics now have the `rev` attribute.mazaitisThis can be used to keep track of what elements in the command set are still boilerplate by incrementing the attribute value after edit.org/ctx_comref/pdf/context_command_reference.pdf
This is pretty straightforward FO. (I imagine ConTeXt could do a nicer job...)=== Output Products ===
=== The Normalized XML ===DITA version of the current effort is here:
`ditahttps://paul.mazaitis.org/ctx_comref/ctx_com_ref-ot` can generate a normalized version of the documentation set:ditanorm-20200622_002.zip
dita --input=context_command_reference.ditamap --format=dita..presented as a zip file (to browse though a smaller example, the prototype is still available online).
httpsOther available formats://paul.mazaitis.org/ctx_comref/normalized-topics/
This transformation does all of the processing work on individual topics HTML5 (coping contentNo CSS, resolving lints, etcZipped): https://paul.mazaitis.) but keeps the content as XML files for further processingorg/ctx_comref/ctx_com_ref-html5-20200622_002.zip
=== Web Help ===PDF (XSL-FO, Full Command Set): https://paul.mazaitis.org/ctx_comref/ctx_com_ref-pdf-20200622_002.pdf
I There are also use the Oxygen XML Editormaps available to build a reference manual with only system commands, which comes and a reference manual with several other transformationsonly user commands. One transformation A PDF version of the documentation set that might be interesting as an example of what is possible is their Web Help implementation, hosted herelatter:
There are many other transformations availableThe documentation still needs to be completed and edited, etc., but I think this could be a viable way to systematically document more of the interface's depth and it is possible to create new onesdetail.
My current work is putting together a programmatic solution for transforming the current XML interface files into a base DITA document set of partially filled topics for every context command.
Reorganization of feature list, features added
== A Hand-Built Prototype ==
I've put together a hand0built hand-built prototype with a handful of commands to act as examples: https://github.com/pmazaitis/context_command_reference_prototype This is meant to be a small scale, easily digestible prototype to show how DITA might be used to develop a comprehensive documentation set. === Output Products === From the hand-built prototype, The DITA Open Toolkit (dita-ot) can generate lots of different formats out of the box, and use plugins for others. Here are some examples, all generated from the above DITA document set. ==== HTML5 ==== `dita-ot` can generate an HTML version of the documentation set: `dita --input=context_command_reference.ditamap --format=html5` ...as hosted here: https://paul.mazaitis.org/ctx_comref/prototype-html5/ This is without any CSS, etc. - just the structure. ==== XSL-FO PDF ==== `dita-ot` can generate an XSL-FO version of the documentation set: dita --input=context_command_reference.ditamap --format=pdf ...as hosted here: https://paul.mazaitis.org/ctx_comref/prototype-pdf/context_command_reference.pdf This is pretty straightforward FO. (I imagine ConTeXt could do a nicer job...) ==== Normalized XML ==== `dita-ot` can generate a normalized version of the documentation set: dita --input=context_command_reference.ditamap --format=dita ...as available here: https://paul.mazaitis.org/ctx_comref/prototype-normalized-topics/ This transformation does all of the processing work on individual topics (coping content, resolving lints, etc.) but keeps the content as XML files for further processing. ==== Web Help ==== I also use the Oxygen XML Editor, which comes with several other transformations. One transformation of the documentation set that might be interesting as an example of what is possible is their Web Help implementation, hosted here: https://paul.mazaitis.org/ctx_comref/prototype-webhelp-responsive/ ==== Other Available Transformations ==== There are many other transformations available, and it is possible to create new ones. == A Full Command Set == === Dita Sources === A full DITA rendering of the ConTeXt command interface is tracked here:
https://github.com/pmazaitis/context_command_reference
These files are generated by a Python script from the command interface files distributed with ConTeXt. The Script is available here:
https://github.com/pmazaitis/context-interface2dita
...with a noted lack of documentation as of yet.
This documentation set is tested to build to PDF, HTML5 and Normalized DITA.
=== 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 `audience` element expresses the intended audience for this topic. This can be used to indicate a level of expertise expected for the audience of this particular command:
There is some flexibility here with the labels.
The `category` element describes one or more categories that this command is part of. A command topic can have multiple `category` elements.
The `keywords` element can support one or more `keyword` elements, to tag commands that fall into more than one area.
The `prodinfo` element contains metadata about how this command topic related to the entire project. The `prodname` element generally links the command to ConTeXt, while the `vrmlist` allows tracking of version (whatever makes sense) and release (which might be useful for production/experimental commands, etc.).
These elements can be used for conditional processing. For example, we could instruct the DITA processor to only include topics that are user-focused, etc.
In addition to the formal metadata, the `prolog` also supports two other pieces of information: the `source` element, and the `critdates` element.
The `source` element may be useful here to describe a full (non-rooted?) path to the source file in the standard ConTeXt distribution.
The `critdates` element can contain `created` and `revised` elements to capture creating, modification, and expiry dates. This element can be used progamatically to identify documentation that is scheduled for an edit.
==== Syntax ====
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).
== Output == Multiple Maps for Multiple Products ====
This one is interesting to me, in that it might be useful as a basis for inclusion and formatting in both ConTeXt documents (through the XML interface) and/or the Wiki (if current methods could be adopted)...as available here:
https://paul.mazaitis.org/ctx_comref/webhelpctx_user_ref-responsive/pdf-20200622_002.pdf
=== Other Available Transformations Much Yet to Do ===
== Pros and Cons ==
== Current Work: Transforming the Current Interface Files ==
Working out a way to manage ''variants'' in the documentation set.
== Future Work ==
