= metanorma-BSI: Metanorma processor for the British Standards Institute

image:https://img.shields.io/gem/v/metanorma-bsi.svg["Gem Version", link="https://rubygems.org/gems/metanorma-bsi"]
image:https://github.com/metanorma/metanorma-bsi/workflows/rake/badge.svg["Build Status", link="https://github.com/metanorma/metanorma-bsi/actions?workflow=rake"]
image:https://codeclimate.com/github/metanorma/metanorma-bsi/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/metanorma/metanorma-bsi"]
image:https://img.shields.io/github/issues-pr-raw/metanorma/metanorma-bsi.svg["Pull Requests", link="https://github.com/metanorma/metanorma-bsi/pulls"]
image:https://img.shields.io/github/commits-since/metanorma/metanorma-bsi/latest.svg["Commits since latest",link="https://github.com/metanorma/metanorma-bsi/releases"]

== Functionality

This gem processes https://www.metanorma.com[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:

[source,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:

[source,console]
----
$ 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

See https://www.metanorma.com/author/iso/[Write ISO documents with Metanorma]

Extensions specific to BSI:

=== Adoptiopn of standard

An adopted external standard is defined as `:adopted-from:`:

[source,asciidoctor]
----
:docidentifier: NA to BS EN 1991-1-2
:adopted-from: EN 1991-1-2
----


[source,asciidoctor]
----
: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.

[source,asciidoc]
----
[[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_
----
____

[source,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_
----
____


[source,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 https://github.com/metanorma/mn-samples-bsi[mn-samples-bsi] repository.
* Document templates are available at the https://github.com/metanorma/mn-templates-bsi[mn-templates-bsi] repository.