anchor.diff:  Asciidoctor-stylesheet-factory::
   You don't need to install this unless you actually want to change the openehr.css or build new stylesheets. See https://github.com/asciidoctor/asciidoctor-stylesheet-factory[here].
   
  +=== Pygments adjustments
  +
  +The Pygments tool is a bit tricky to manage. The pygments.rb installation contains a static copy of an old snapshot of the main pygments Python project in its `vendor` directory. To achieve this, you will need to clone the original project. The best way to do this right now is to clone https://bitbucket.org/thomas_beale/pygments-maint[his Bitbucket] fork of it, which contains the Archetype language additions (enabling colourising of adl, cadl, odin syntax), and then copy the contents of that into the `vendor` area of the `pygments.rb` install (which will be wherever your Ruby gems are being installed).
  +
  +Then you will need to go to the root directory of the `pygments.rb` install area, and run `cache-lexers.rb` to update the lexers cache file..
  +
  +This is not ideal and hopefully, the `pygments.rb` project (which is just a Ruby wrapper around Pygments, which is in Python) will be updated to a better method or replaced within Asciidoctor proper.
  +
   === MagicDraw and UML Extractor
  -If you have MagicDraw, you can install the UML extractor plugin in MagicDraw's plugin directory, under `org.openehr.docs.magicdraw`. The plugin files consist of one `.jar` and the `plugin.xml` file.  With this installed, start MagicDraw and open the project link:computable/UML/[openEHR_UML-AM.mdzip]. You will see an 'openEHR' menu option, with one option to extract documentation. Choose this, and choose `source/AOM2` as the output directory. The generated outputs will appear in the subdirectories `uml_diagrams` and `classes`.
  +If you have MagicDraw, you can install the UML extractor plugin (files `OpenEhrModelExporter.jar` and `plugin.xml` in `/uml_extract/OpenEhrModelExporter` in this repository) in the MagicDraw install area  directory on your machine, under `/plugin/org.openehr.docs.magicdraw`. 
  +
  +The extract can now be done manually, which is the normal method for this repository, or by using a command line invocation, which is the way it can most easily be done in the production component repositories (`specifications-RM`, etc).
  +
  +*Manual method*: start MagicDraw and open the project link:computable/UML/[openEHR_UML-AM.mdzip]. You will see an 'openEHR' menu option, with one option to extract documentation. Choose this, and choose `source/AOM2` as the output directory. The generated outputs will appear in the subdirectories `uml_diagrams` and `classes`.
  +
  +*CLI method*: go to the root of the repository you are working in (e.g. a component one such as `specifications-RM`) and do:
  +
  +[source, sh]
  +----
  +$ ./do_uml_generate-spec-RM.sh # or do_uml_generate-spec-AM.sh etc
  +----
  +
  +== The Process
   
   === Conversion of FrameMaker and other source documents
  -For conversion from Frame, the following approach is used:
  +For conversion from Frame, various approachs are used including the following:
   
   * in Frame, for each chapter document, including 'Front.fm', but not TOC or end.fm, set HTML mappings for Heading types, List types and main Font types
   * save each chapter as HTML
  
positive.code: 
  * control PDF publishing properly
  * sort out continuous build
  
negative.code: 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 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 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.
  
  