Functionality
This gem processes Metanorma documents following the Metanorma model for generating BSI standards.
The gem is basically the https://github.com/metanorma/metanorma-iso gem, with some tweaking of rendering to meet the particular requirements of the BSI.
It provides the following functions:
-
Compiles Metanorma input into the Metanorma-BSI XML format (which is identical to Metanorma-ISO, since the two standards share the same document model)
-
Validates XML output against the Metanorma-BSI document model
-
Errors are reported to console against the XML, and are intended for users to check that they have provided all necessary components of the document.
-
-
Metanorma-BSI XML is then converted into desired output formats.
The following outputs are supported:
-
Primary: the canonical Metanorma-BSI XML representation (
.xml
). -
Secondary: the Metanorma-BSI XML representation is processed to generate the following outputs as end deliverable BSI documents.
-
HTML (
.html
) -
Word (
.doc
)
-
Structure
This gem inherits from the https://github.com/metanorma/metanorma-iso gem, and aligns closely to it.
Quickstart
Please see https://www.metanorma.com for instructions to get started.
If you are using a Mac, the https://github.com/metanorma/metanorma-macos-setup repository has instructions on setting up your machine to run Metanorma scripts such as this one. You need only run the following in a Terminal console:
$ bash <(curl -s https://raw.githubusercontent.com/metanorma/metanorma-macos-setup/master/metanorma-setup)
$ gem install metanorma-cli
$ gem install metanorma-bsi
Usage
Using the metanorma
CLI:
$ metanorma --type bsi a.adoc # output HTML
$ metanorma --type bsi --extensions html a.adoc # output just HTML
$ metanorma --type bsi --extensions xml a.adoc # output Metanorma XML
Authoring
Please refer to the Metanorma-ISO documentation for general documentation.
-
Metanorma-ISO general documentation: https://www.metanorma.com/software/metanorma-iso/
-
Metanorma-ISO guidance: https://www.metanorma.com/software/metanorma-iso/docs/guidance/
Documentation
Extensions specific to BSI:
Adoptiopn of standard
An adopted external standard is defined as :adopted-from:
:
:docidentifier: NA to BS EN 1991-1-2
:adopted-from: EN 1991-1-2
:docidentifier: BS ISO 639-2
:adopted-from: ISO 639-2
Commentaries
Commentaries are entered as notes of type commentary
,
with an optional target
attribute,
giving the anchor of the block the commentary is referencing. If no target
is given, the commentary is assumed to be about the subclause containing it.
[[reag]]
=== Reagents
[NOTE,type=commentary,target=reag]
This is a commentary on the reagents
[[table1]]
.Reagents in use
|===
| A | B
|===
7.6 Reagents
COMMENTARY ON CLAUSE 7.6 This is a commentary on the reagents
A
B
Table 1: Reagents in use
</pre> </div> </div> </blockquote> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">[[reag]] === Reagents [NOTE,type=commentary] This is a commentary on the reagents [[table1]] .Reagents in use |=== | A | B |===
7.6 Reagents
COMMENTARY ON CLAUSE 7.6 This is a commentary on the reagents
A
B
Table 1: Reagents in use
</pre> </div> </div> </blockquote> </div> <div class="listingblock"> <div class="content"> <pre class="highlight"><code class="language-asciidoc" data-lang="asciidoc">=== Reagents [NOTE,type=commentary,target=table1] This is a commentary on the table [[table1]] .Reagents in use |=== | A | B |===
7.6 Reagents
COMMENTARY ON TABLE 1 This is a commentary on the table
A
B
Table 1: Reagents in use
Examples
-
Example documents are avalable at the mn-samples-bsi repository.
-
Document templates are available at the mn-templates-bsi repository.