RubyDoc.info: File: README – Documentation for metanorma-standoc (1.0.7)

Warning

This gem is still under development.

Gem for serialising the Metanorma Standoc model.

Asciidoctor model additions

Section titles

Metanorma standards has special section types: "Scope", "Normative References", "Terms and Definitions", "Symbols and Abbreviated Terms", "Bibliography". By default, these are identified in Asciidoc by using those titles. The gem allows you to override the title by using a heading attribute on the node, so that the actual title in your Asciidoc can be something different; that is useful, for example, if you are translating the document into different languages. So:

[heading=scope]
== 范围

Note that both the XML population, and the isodoc gem will overwrite any supplied title. If you are translating Metanorma documents into other languages, you will still need access to versions of the metanorma-standoc and isodoc gems in those languages.

Obligation

The obligation of sections (whether they are normative or informative) is indicated with the attribute "obligation". For most sections, this is fixed; for annexes and clauses, the default value of the obligation is "normative", and users need to set the obligation to "informative" as a section attribute.

[[AnnexA]]
[appendix,obligation=informative]
== Determination of defects

Term markup

To ensure the structure of Terms and Definitions is captured accurately, the following macros are defined, and must be used to mark up their respective content:

alt:[TERM]: for alternative terms
deprecated:[TERM]: for deprecated terms
domain:[TERM]: for term domains

The macro contents can contain their own markup.

=== paddy
alt:[_paddy_ rice]
deprecated:[#[smallcap]#cargo# rice]
domain:[rice]

_paddy_ (<<paddy>>) from which the husk only has been removed

Terms and Definitions markup

If the Terms and Definitions of a standard are partly or fully sourced from another standard, that standard is cited in a source attribute to the section, which is set to the reference anchor of the standard (given under the Normative Referencecs).. The boilerplate of the Terms and Definitions section is adjusted accordingly.

[source=ISO712]
== Terms and Definitions

Multiple sources are allowed, and need to be quoted and comma-delimited:

[source="ISO712,ISO24333"]
== Terms and Definitions

Paragraph alignment

Alignment is defined as an attribute for paragraphs:

[align=left]
This paragraph is aligned left

[align=right]
This paragraph is aligned right

[align=center]
This paragraph is aligned center

[align=justified]
This paragraph is justified, which is the default

Reviewer notes

Reviewer notes are encoded as sidebars, and can be separated at a distance from the text they are annotating; the text they are annotating is indicated through anchors. Reviewer notes are only rendered if the document has a :draft: attribute.

The following attributes on reviewer notes are mandatory:

reviewer attribute (naming the reviewer)
the starting target anchor of the note (from attribute)

The following attributes are optional:

date attribute, optionally including the time (as xs:date or xs:datetime)
the ending target anchor of the note (to attribute)

The span of text covered by the reviewer note is from the start of the text encompassed by the from element, to the end of the text encompassed by the to element. If only the from element supplied, the reviewer note covers the from element. The from and to elements can be bookmarks, which cover no space.

[[clause_address_profile_definition]]
=== Address Profile Definition (AddressProfileDescription)

[[para1]]
This is a clause address [[A]]profile[[B]] definition

[reviewer="Nick Nicholas",date=20180125T0121,from=clause_address_profile_definition,to=para1]
****
I do not agree with this statement.
****

[reviewer="Nick Nicholas",date=20180125T0121,from=A,to=B]
****
Profile?!
****

Strikethrough and Small Caps

The following formatting macros are used for strikethrough and small caps text:

[strike]#strike through text#
[smallcap]#small caps text#

Count of table header and footer rows

In Asciidoc, a table can have at most one header row or footer row. In Metanorma, a nominal single header row is routinely broken up into multiple rows in order to accommodate units or symbols, that line up against each other, though they are displayed as merged cells with no grid between them. To address this, tables can be marked up with an optional headerrows attribute:

[headerrows=2]
|===
.2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice +
stem:[w_max]
| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice

| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5
|===

Inline clause numbers

For some clauses (notably test methods), the clause heading appears inline with the clause, instead of being separated on a different line. This is indicated in Asciidoc by the option attribute inline-header:

[%inline-header]
[[AnnexA-2-1]]
==== Sample divider,

consisting of a conical sample divider

Bibliographic details

Citations can include details of where in the document the citation is located; these are entered by suffixing the type of locality, then an equals sign, then the reference. The word "whole" on its own is also treated as a locality. Multiple instances of locality and reference can be provided, delimited by comma or colon. Any trailing text after the sequence of locality=reference (or locality, space, reference) are treated as substitute text, as would occur normally in an Asciidoctor crossreference. For example:

<<ISO712,the foregoing reference>>     # renders as: the foregoing reference
<<ISO712,section=5, page 8-10>>         # renders as: ISO 712, Section 5, Page 8-10
<<ISO712,section=5, page=8-10: 5:8-10>> # renders as ISO 712, 5:8-10 ("5:8-10" treated as replacement text for all the foregoing)
<<ISO712,whole>>                        # renders as: ISO 712, Whole of text

The references cannot contain spaces. Any text following the sequence of localities will be displayed instead of the localities.

A custom locality can be entered by prefixing it with locality::

<<ISO712,locality:frontispiece=5, page=8-10>>         # renders as: ISO 712, Frontispiece 5, Page 8-10

Custom localities may not contain commas, colons, or space. Localities with the locality: prefix are recognised in internationalisation configuration files.

Block Quotes

As in normal Asciidoctor, block quotes are preceded with an author and a citation; but the citation is expected to be in the same format as all other citations, a cross-reference optionally followed by text, which may include the bibliographic sections referenced:

[quote, ISO, "ISO7301,section 1"]
_____
This International Standard gives the minimum specifications for rice (_Oryza sativa_ L.)
which is subject to international trade. It is applicable to the following types: husked rice
and milled rice, parboiled or not, intended for direct human consumption. It is neither
applicable to other products derived from rice, nor to waxy rice (glutinous rice).
_____

Image size

The value auto is accepted for image width and height attributes. It is only passed on to HTML output; if the output is to Word, both the width and height attributes are stripped from the image.

[height=90,width=auto]
image::logo.jpg

Subclauses in Terms & Definitions sections

Normally any terminal subclause in a Terms & Definitions section is treated as a term definition. Exceptionally, an introductory section can be tagged to be treated as a clause, instead of a term, by prefixing it with the style attribute [.nonterm].

== Terms and definitions

[.nonterm]
=== Introduction
The following terms have non-normative effect, and should be ignored by the ametrical.

=== Anapaest

metrical foot consisting of a short, a long, and a short

Sections embedded more than 5 levels

Asciidoctor permits only 5 levels of section embedding (not counting the document title). Standards do contain more levels of embedding; ISO/IEC DIR 2 only considers it a problem if there are more than 7 levels of embedding. To realise higher levels of embedding, prefix a 5-level section title with the attribute level=:

====== Clause 5

[level=6]
===== Clause 6

[level=7]
====== Clause 7A

[level=7]
====== Clause 7B

[level=6]
====== Clause 6B

====== Clause 5B

This generates the following ISO XML:

<clause id="_" inline-header="false" obligation="normative">
	<title>
		Clause 5
	</title>
	<clause id="_" inline-header="false" obligation="normative">
		<title>
			Clause 6
		</title>
		<clause id="_" inline-header="false" obligation="normative">
			<title>
				Clause 7A
			</title>
		</clause>
		<clause id="_" inline-header="false" obligation="normative">
			<title>
				Clause 7B
			</title>
		</clause>
	</clause>
	<clause id="_" inline-header="false" obligation="normative">
		<title>
			Clause 6B
		</title>
	</clause>
</clause>
<clause id="_" inline-header="false" obligation="normative">
	<title>
		Clause 5B
	</title>
</clause>

PlantUML

The PlantUML diagramming tool is integrated with Asciidoctor in this gem, as a literal block with the style attribute plantuml:

[plantuml]
....
@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
@enduml
....

The integration runs PlantUML for each such block, generating a PNG image. The images are stored in the plantuml directory, and linked into the output document in place of the PlantUML.

PlantUML needs to be installed by users separately, and accesssible from the command line:

brew install plantuml on MacOS.
For Linux, link the PlantUML jar file into a command line executable; see .travis.yml for an example.

If PlantUML is not installed locally, the source PlantUML is incorporated into the output document as sourcecode.