Add instructions on how to use mnconvert: convert other formats into Metanorma AsciiDoc

[ronaldtse]

For STS XML:

• Convert ISO STS into XML
• Convert NISO STS into XML

For IEEE SA:

• Add IEEE SA XML to Metanorma AsciiDoc conversion functionality mnconvert#183
• IEEE SA has indicated that they need to use this for converting old documents to kick start revision projects

@Intelligent2013 could you please help list out all the formats that mnconvert supports, and some instructions for them? Thanks.

[Intelligent2013]

mnconvert supports conversion for:

• ISO/NISO STS

  • ISO/NISO STS XML to Metanorma AsciiDoc

    Command line:
    java -jar mnconvert-1.20.0.jar <path to input STS XML> --output <path to output Metanorma AsciiDoc>

    Example:
    java -jar mnconvert-1.20.0.jar ./Examples/30386407.xml --output ./Examples/adoc/30386407.adoc

  • ISO/NISO STS XML to Metanorma XML (semantic and presentation)

    Command line:
    java -jar mnconvert-1.20.0.jar <path to input STS XML> --output <path to output Metanorma XML> --output-format xml

    Example:
    java -jar mnconvert-1.20.0.jar ./Examples/30386407.xml --output ./Examples/xml/30386407.mn.xml --output-format xml

    NOTE: by default, mnconvert generates Metanorma presentation XML, but you can specify the parameter --semantic to generate Metanorma semantic XML:
    java -jar mnconvert-1.20.0.jar ./Examples/30386407.xml --output ./Examples/xml/30386407.mn.semantic.xml --output-format xml --semantic

    NOTE: by default, mnconvert determines Metanorma XML root element by standard office's abbreviation, for instance <iso-standard ... for ISO documents, <bsi-standard ... for BSI documents. But you can specify the prefix for the root element obviously by the parameter --type iso.

  • Metanorma XML (semantic and presentation) to ISO/NISO STS XML

    Command line:
    java -jar mnconvert-1.20.0.jar <path to input Metanorma XML> --output <path to output ISO/NISO STS XML>

    Example:
    java -jar mnconvert-1.20.0.jar ./Examples/rice-en.final.presentation.xml --output ./Examples/xml/rice-en.final.sts.niso.xml

    NOTE: by default, mnconvert generates STS NISO XML, but you specify the parameter --output-format iso to generate STS ISO XML.

    NOTE: by default, mnconvert validates generated STS NISO XML against XSD NISO-STS-interchange-1-MathML3-XSD, but you can specify the tag-set (interchange or extended) and MathML version (2 or 3) obviously via the parameters, for instance --tagset extended --mathml 2, to select another NISO-STS XSD.

• IEEE SA

  • from IEEE XML STL v1.7 to Metanorma AsciiDoc

    Command line:
    java -jar mnconvert-1.20.0.jar <path to IEEE XML> --output <path to output Metanorma AsciiDoc>

    Example:
    java -jar mnconvert-1.20.0.jar ./Examples/2830-2021.xml --output ./Examples/adoc/ieee/2830-2021.adoc

  • from Metanorma XML (semantic) to IEEE XML STL v1.7

    Command line:
    java -jar mnconvert-1.20.0.jar <path to Metanorma semantic XML> --output <path to output IEEE XML> --output-format ieee -- validation-against <path to IEEE STL DTD>

    Example:
    java -jar mnconvert-1.20.0.jar ./Examples/document.xml --output ./Examples/xml/document.ieee.xml --output-format ieee --validation-against ./standards-1-7-DTD/standards-1-7-dtd/standards.dtd

• RFC

  • from RFC XML (v2 and v3) to Metanorma AsciiDoc IETF

    Command line:
    java -jar mnconvert-1.20.0.jar <path to RFC XML> --output <path to output Metanorma AsciiDoc IETF>

    Example:
    java -jar mnconvert-1.20.0.jar ./Examples/rfc8685.xml --output ./Examples/adoc/rfc8685.adoc

NOTE: by default mnconvert is looking for images in the folder 'images' near the input XML, but you can specify another relative path via the parameter --imagesdir <relative path to the folder with images>. For instance, if images placed in the same folder as input XML file, then you can specify this value: --imagesdir ./.

• DOCX

  • from DOCX (generated by Metanorma in DOC in 'ISO Simple Template' or 'ISO Edited DIS Template', and re-saved in DOCX) to Metanorma AsciiDoc

    Command line:
    java -jar mnconvert-1.20.0.jar <path to DOCXL> --output <path to output Metanorma AsciiDoc>

    Example:
    java -jar mnconvert-1.20.0.jar ./Examples/rice-en.final.docx --output ./Examples/adoc_docx/rice-en.final.adoc