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_referenceMaps could also be made to support command glossaries for manuals, etc.ditamap --format=html5`
...as hosted here:
https://paul.mazaitis.org/ctx_comref/prototype-html5/==== Keeping Track of What Needs To Be Worked On ====
This is without any CSS, etc. - just Several elements in the topics now have the structure. === XSL-FO PDF === `dita-otrev` can generate an XSL-FO version of the documentation set: dita --input=context_command_reference.ditamap --format=pdf attribute...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 used to keep track 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 elements in the ConTeXt command interface is available here: https://github.com/pmazaitis/context_command_reference ...generated by a fairly scary Python script from the command interface files distributed with ConTeXt. This documentation set builds cleanly into HTML5, PDF, and Normalized DITA. There are caveats! This documentation set badly needs to be edited; there are places in spot-checking the commands where the script made wildly incorrect interpretations of still boilerplate by incrementing the interface. It turns out that chains of inheritance play badly; all of the inheritance in this documentation set has been flattened. (For example, instead of a command inheriting settings from `\blank` which in turn inherits from `\vspacing`, the command inherits from `\vspacing`.) There are some quirks! For example commands were listed as inheriting options (single keywords) from `\setuppapersize`, but `\setuppapersize` only had settings (key/attribute value pairs). I did the best I could to untangle thoseafter edit.
I've prepared three formats for The Normalized DITA version of the entire command setcurrent effort is here: HTML, PDF, and Normalized Dita.
The HTML5 version is hosted herehttps://paul.mazaitis.org/ctx_comref/ctx_com_ref-ditanorm-20200622_002.zip
https://paul.mazaitis.org/ctx_comref/full-html5/index.htmlpresented as a zip file (to browse though a smaller example, the prototype is still available online).
...This one is interesting to me, in that it might be useful as a basis for interactive explorationinclusion and formatting in both ConTeXt documents (through the XML interface) and/or the Wiki (if current methods could be adopted).
The PDF (XSL-FO version is hereOther available formats:
Which brings us There are also maps available to build a reference manual with only system commands, and a reference manual with only user commands. A PDF version of the Normalized DITAlatter:
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 ===
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 ====
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 ====
=== Output Products ===
HTML5 (No CSS, Zipped): https://paul.mazaitis.org/ctx_comref/fullctx_com_ref-pdf/context_command_referencehtml5-20200622_002.pdfzip
PDF (XSL-FO, Full Command Set): https://paul.mazaitis.org/ctx_comref/ctx_com_ref-pdf-20200622_002.and it's worth noting that this behemoth requires upping the Java memory limit to 3GB (!) to finish compiling, and the resulting output is function, but could be more pleasant.pdf
https://paul.mazaitis.org/ctx_comref/fullctx_user_ref-normalized_dita.zip ...presented as a zip file (to browse though a smaller example, the prototype is still available online). 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 adoptedpdf-20200622_002.pdf
=== Much Yet to Do ===
The 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 detail.
== Pros and Cons ==
