Metanorma: Aequitate Verum

Developer documentation

Using Metanorma with an existing input format

Summary

I can translate my specifications into Metanorma XML myself (i.e. I don’t like Metanorma AsciiDoc or Metanorma LaTeX, or I already have my own toolchain). Can I only use Metanorma XML to produce pretty output?

Yes you can!

Tip
Summary

  • Generate correct Metanorma XML (make sure it validates!)

  • Create just the IsoDoc::…​::HtmlConvert and/or IsoDoc::…​::WordConvert classes to convert the Metanorma XML into target formats.

  • Initialise the IsoDoc class passing the necessary information about fonts and scripts; the existing gems all illustrate this kind of initialization.

  • Create the target format using the method .convert(filename, xml).

Method

The “Metanorma AsciiDoc to Metanorma XML”, and “Metanorma XML to Output” classes are separate, so you can invoke just the latter without the former. Of course, you will need to make sure that the Metanorma XML you are passing to the generators is valid.

The IsoDoc::…​::HtmlConvert and/or IsoDoc::…​::WordConvert are initialised in the existing gems with a hash giving the fonts to be used in the document (to be injected in the document SCSS stylesheets), the script of the document (to be used to pick the right font, in case of default font settings), and the i18nyaml YAML file for localization. All existing gems have defaults set for these values on the AsciiDoc side invoking the class, so all parameters are optional.

Once you have the classes set up, all you need to do is invoke the conversion of XML to the target format, with the method .convert(filename, xml), where XML is the Metanorma XML.