anchor.diff:  Specification publishing using Asciidoc and UML
   
   == Purpose
  -This repository contains a model publishing environment showing how technical specifications can be published in HTML, PDF and DocBook, based on authored content merged with UML models from a tool. The method will be used to replace openEHR.org's current method of publishing based on Adobe FrameMaker documents.
  +
  +This repository contains a model publishing environment showing how technical specifications can be published in HTML, PDF and DocBook, based on authored content merged with UML models from a tool. The method replaces openEHR.org's previous method of publishing based on Adobe FrameMaker documents.
   
   The type of technical specifications for which this approach is useful is standard-style documentation of formal artefacts, including:
  +
   * object models
   * languages
   * other formalisms.
   
   == Description
  -The publishing environment takes two sources of input to create a logical specification:
  -* manually authored text (.adoc documents) and diagrams (any tool, as long as .png or .svg is generated)
  -* a formal UML model, represented in a UML tool.
  +
  +The publishing environment takes various sources of input to create a logical specification:
  +
  +* manually authored text (`masterxxx.adoc` documents) and diagrams (any tool, as long as `.png` or `.svg` is generated);
  +* a formal UML model, represented in the MagicDraw UML tool;
  +* other resources, e.g. Antlr3 or Antlr4 grammar files.
   
   We use http://asciidoctor.org/docs/what-is-asciidoc/[Asciidoc] as the source document syntax, the http://www.nomagic.com/[MagicDraw] UML tool for the models and http://asciidoctor.org[Asciidoctor] as the master publishing tool.
   
   The general concept is that the overall specification is considered to be a manually authored artefact, which may include headings, complex formatting, tables, diagrams, source code, and any other features that would normally be expected in a sophisticated authoring toolset. Within this master document are 'include' statements for documents and diagrams generated from a formal model, such as a UML tool or programming environment.footnote:[There is an alternative theory that says specifications are completely represented inside a tool such as a UML tool, and it is responsible for generating the whole output. We don't believe this theory, mainly because UML tools are not good at dealing with arbitrary complex text, and also because UML isn't the only possible formalism that might be included in the output document. What is clearly needed is a standardised publishing environment that can deal with specifications about anything.]
   
   Model elements are extracted from the UML tool and serialised as source documents and diagrams that are included in the master Asciidoc document using include statements.
  +
  +Other content, e.g. parse files, are pulled into the Asciidoctor file by `include` statements.
   
   The outputs are generated using asciidoctor tool.
   
  
positive.code: 
  * control PDF publishing properly
  * sort out continuous build
  
negative.code: 
  Have a look at this script to get an idea of how we are invoking asciidoctor.
  
  === Status of PDF
  
  Currently, the PDF output is not usable, but Asciidoctor-pdf is being worked on heavily, and the next release will include a lot of fixes. We should be able to generate decent PDFs for openEHR after that.
  
  === Other output formats
  
  There is an epub extension for Asciidoctor. This has not yet been integrated to the environment here, but could be, and should in theory enable us to generate .epub files.
  
  === Resources, styles and themes for HTML and PDF
  
  We are using a stylesheet generated using the asciidoctor-stylesheet-factory; it is in `./resources/css/`. An early theme file for PDF, built according to the http://gist.asciidoctor.org/?github-asciidoctor%2Fasciidoctor-pdf%2F%2Fdocs%2Ftheming-guide.adoc[Asciidoctor-pdf theming guide] is in `./resources` as well.
  
  == TODO
  