readme

README.adoc

@@ -99,19 +99,17 @@ DocBook document authoring tool). Asciidoctor has built-in capability to output
 Text, DocBook and HTML; so it can be used to preview the file as it is being
 authored.
 
-Note that in order to generate HTML preview output close to what is intended
-in the M3D standard, the Asciidoc
-document includes a fair amount of formatting instructions (e.g. disabling
-section numbering where appropriate, the titling of Appendixes as Annexes), as
-well as M3D boilerplate text, and predefined section headers (sections are
-recognised by fixed titles such as `Normative References`). Authoring M3D
-standards in this fashion assumes that users will be populating an Asciidoc
-template, and not removing needed formatting instructions.
+Generating documents via a document model substantially automated formatting
+associated with the document, including automating numbering of headings, figures,
+tables etc, and automatically generating references and citations.
 
 == Document Attributes
 
+=== Common attributes
+
 The gem relies on Asciidoctor document attributes to provide necessary
-metadata about the document. These include:
+metadata about the document. The https://github.com/riboseinc/metanorma-standoc[metanorma-standoc]
+gem documents the Asciidoctor document attributes common to all metanorma gems. These include:
 
 `:edition:`:: The document edition
 
@@ -147,7 +145,11 @@ report:: report
 The attribute `:draft:`, if present, includes review notes in the XML output;
 these are otherwise suppressed.
 
-== AsciiM3D features not also present in AsciiISO
+== Asciidoctor features specific to CSAND
+
+The https://github.com/riboseinc/metanorma-standoc[metanorma-standoc]
+gem documents the customisations of Asciidoctor markup common to all metanorma gems.
+The following markup is specific to this gem:
 
 * `+[keyword]#...#+`: encodes keywords, such as "MUST", "MUST NOT". (Encoded as
 `<span class="keyword">...</span>`.