A Markup Language for Documenting BabelScript
Saturday, May 1st, 2010So far the very small amount of documentation that I’ve written concerning BabelScript, aside from these blog posts, has been created using DocBook. I will shortly be adding the predicate definitions covering computer terminology, but rather than continue in the same manner this strikes me as an almost ideal candidate for a custom markup language that can be transformed using XSL:
- The final result will be large but highly structured, consisting of many thousands of predicate descriptions that (with a few notable exceptions such as numbers) all follow broadly the same pattern.
- I would strongly prefer not to commit to any particular layout at the present time.
- It is quite conceivable that there will be a need to present the documentation in several ways, with different layout and perhaps also different content
The elements currently defined are:
babelscriptml, the root of the documenttopic, corresponding to a top-level namespacesubtopic, corresponding to a second- or lower-level namespacetitle, the title of a topic or subtopicnaming, specifying how predicates are named in a topic or subtopic if this is done systematicallypredicate-def, the definition of a predicate containing (at least) the predicate defined and a descriptionpredicate, the name of a predicatedescription, a description of a predicate, topic or subtopiccompare, a predicate that it is instructive to compare with the one being describednote, an additional comment within a topic, subtopic or predicate definition
This is not intended to be a final list, but I won’t be adding anything that is not needed for the task in hand. The markup is strictly ad hoc in nature, and I do not intend to worry about forward or backward compatibility with anything outside the Project Babel source repository.