Merge branch 'doc20230419' into doc20230606

author/topics/document-format/bibliography.adoc

@@ -1242,7 +1242,7 @@ The following input:
 
 ...
 
-* [[[ISO7301,path(./iso7301.html,ISO 7301)]]]
+* [[[ISO7301,path:(./iso7301.html,ISO 7301)]]]
 --
 
 will render in HTML as:
@@ -1281,6 +1281,30 @@ rendered [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v
 --
 ====
 
+==== Styled cross-references
+
+As with link:/author/topics/document-format/xrefs#xref-styles[internal cross-references], cross-referenced
+citations can have a `style` attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4].
+As of this writing, the only values allowed are the types of docidentifier value that can be substituted
+for the primary identifier of the reference, for standards documents; those values will need to be looked up in
+Relaton (and the Semantic XML of the document). For example, given the citation
+
+[source,xml]
+----
+<bibitem type="standard" id="bib1">
+...
+<docidentifier type="ISO" primary="true">ISO/FDIS 17664-1</docidentifier>
+<docidentifier type="URN">urn:iso:std:iso-fdis:17664:-1:ed-1:fr</docidentifier>
+...
+</bibitem>
+----
+
+a crossreference `<<bib1>>` will be populated by default with the primary or else the first
+`docidentifier` value found, `ISO/FDIS 17664-1`. However, given `<<bib1,style=URN%>>`, the
+first `docidentifier` value of type `URN` will be sought instead, and the cross-reference
+will be populated by default as `URN urn:iso:std:iso-fdis:17664:-1:ed-1:fr`.
+
+
 === Link-only references
 
 A standards document can be cross-referenced in Metanorma without that document
@@ -1470,3 +1494,35 @@ The following encoding will hide the particular bibliographic reference.
 * [[[iso86011,hidden(ISO 8601-1:2019)]]]
 --
 ====
+
+=== CSV notation
+
+The notation shown up to this point for reference processing flags has the potential of being too complicated
+to parse, if deeply nested or if the parentheses of flags are combined with the parentheses of user-supplied
+labels or of "all parts". For that reason, an alternative notation is supported, involving key/value pairs
+delimited by comma and equals signs in the anchor label [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4].
+For example, the following two references are equivalent:
+
+[source,asciidoc]
+----
+[bibliography]
+== Normative references
+
+* [[[iso8601_1,nofetch((Date-Time)ISO 8601-1:2019)]]], _Date and time — Representations for information interchange — Part 1: Basic rules_
+* [[[iso8601_1a,nofetch=true,usrlabel=Date-Time,code=ISO 8601-1:2019]]], _Date and time — Representations for information interchange — Part 1: Basic rules_
+----
+
+The CSV-based notation has the following keys:
+
+`nofetch`:: `true`|`false`
+`hidden`:: `true`|`false`
+`dropid`:: `true`|`false`
+`local-file`:: (filename of local Relaton cache)
+`repo`:: (repository name)/(document entry)
+`path`:: (file path)
+`number`:: (number, for a numeric ID of a citation)
+`usrlabel`:: (user-supplied label of reference)
+`code`:: (authoritative identifier of reference)
+
+If no key is supplied in the CSV entry, it is assumed to be a code; e.g. `nofetch=true,usrlabel=Date-Time,ISO 8601-1:2019`
+is interpreted as `nofetch=true,usrlabel=Date-Time,code=ISO 8601-1:2019`.

author/topics/document-format/indexes.adoc

@@ -184,6 +184,35 @@ levels deep.
 In some flavours, a separate table of contents is inserted for figures, tables,
 and recommendations.
 
+=== Automated table of contents generation
+
+The table of contents is generated automatically for Word, HTML, and PDF output.
+
+* In Word, it takes the form of a normal Word Table of Contents; the page numbers
+are not populated when the document is generated, and the table of contents needs
+to be refreshed (Right Click: Update Field).
+* In HTML, it takes the form of a side panel. In PDF, it takes the form of an
+introductory table of contents; because the PDF is generated from HTML in Metanorma,
+there are no page numbers in the table of contents.
+
+By default, the table of contents includes two levels of heading. More levels of
+heading can be set by using the document attribute `:toclevels:`; e.g.
+`:toclevels: 3` for three levels of heading included. The number of levels of heading
+to include can be set separately for HTML and for DOC/PDF, by using the document
+attributes `:htmltoclevels:`, `:pdftoclevels:` and `:doctoclevels:`.
+
+The location of the table of contents is set by default for each flavour, and is normally
+at the start of the document preface. If the user wishes to insert a signpost for tables of content,
+the clause type `toc` is reserved to indicate
+where the table of contents will go. But Metanorma by default will not allow any flexibility
+in where the table of contents will be rendered --- and will move it to the start of the preface.
+
+[source,adoc]
+----
+[.preface,type=toc]
+== Table of contents
+----
+
 === Using the `toc` command to generate a ToC
 
 A manual table of contents command has been added to

author/topics/document-format/sections.adoc

@@ -575,23 +575,6 @@ and the rendering would be something like
 *1.1.1.1.2  Clause 5B*
 
 
-== Table of Contents
-
-The table of contents is generated automatically for Word, HTML, and PDF output.
-
-* In Word, it takes the form of a normal Word Table of Contents; the page numbers
-are not populated when the document is generated, and the table of contents needs
-to be refreshed (Right Click: Update Field).
-* In HTML, it takes the form of a side panel. In PDF, it takes the form of an
-introductory table of contents; because the PDF is generated from HTML in Metanorma,
-there are no page numbers in the table of contents.
-
-By default, the table of contents includes two levels of heading. More levels of
-heading can be set by using the document attribute `:toclevels:`; e.g.
-`:toclevels: 3` for three levels of heading included. The number of levels of heading
-to include can be set separately for HTML/PDF and for DOC, by using the document
-attributes `:toclevels-html:` and `:toclevels-doc:`.
-
 == Colophon sections
 
 Metanorma supports non-normative clauses appearing at the end rather than the beginning

author/topics/document-format/xrefs.adoc

@@ -53,7 +53,7 @@ in the AsciiDoc source
 (e.g. `\<<``formulaB-1``>>` generates either "`Formula (B.1)`" or "`B.6, Formula (B.1)`",
 depending on where in the document it occurs.)
 
-
+[[xref-styles]]
 == Cross-reference styles
 
 Metanorma supports multiple cross-reference styles [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.6].