Attendees: Nicolas, Yves
From Nicolas' notes:
We discussed Steve’s approach for generating DocBook documents from ontologies via a small library (in Ruby) of helper methods for constructing well-formed chunks of DocbBook.
In the TIWG, we had been following a model-based approach based on distinguishing between:
- The input model(s) – e.g. a metamodel like UML, a profile like SysML, a library like QUDV or ISO80K, an ontology like JPL’s
- The document model whose organization reflects the organization of the output document in some format (e.g., LibreOffice, DocBook, LaTeX, PDF, …)
Generating the output document from the document model should be a simple transformation because the document metamodel is designed to be easily mapped to document formats like DocBook, LibreOffice, LaTeX, … In the TIWG, we had been using the Eclipse-based GenDoc templating language for doing this generation. JPL’s DocGen uses a kind of UML Activity diagram-based language for a similar purpose.
To accommodate the needs of specification documents, these templating languages allow invoking functions written in a programming language of some kind.
Instead of using a template language as a programming language, we discussed using Scala in a restricted way to get compact, readable code where the type signature of a function
provides a useful compact specification of what a function does.
Looking at Steve’s jpl/docbook.rb library of helper methods for constructing chunks of well-formed DocBook, we discussed the idea of extracting the typology
of document structures involved in OMG’s specifications (UML and SysML) as a document metamodel that could be easily mapped to an output document in some document
format using a library of helper functions for assembling documents in that document format.
For example, this document metamodel could look like this (in Scala):
class SpecDocument(title: String, version: String, sections: Seq[Section], …)
class Section(title: String, number: String, para: Seq[SubSection])
class Metaclass(title: String, description: Seq[Paragraph], href: URL extends SubSection
class Stereotype(title: String, description: Seq[Paragraph], href: URL) extends SubSection
Here’s a sketch of a document model for SysML 1.4:
Stereotype("BLock", Seq(...), url("http://www.omg.org/spec/SysML/1.4/Block"))
Yves volunteered to extract a document metamodel from the typology of document templates he had developed in GenDoc for OMG’s UML & SysML specification documents.