chore: update documentation

author/topics/collections/configuration.adoc

@@ -120,21 +120,21 @@ Metanorma [added in https://github.com/metanorma/metanorma/releases/tag/v1.3.5].
 This is automatically included when `sectionsplit` is set in the
 Metanorma file, to break a single document up into multiple HTML files.
 
-`coverpage: ...`:::
+`coverpage: {file-path}`:::
 Gives the location of the HTML coverpage, as an alternative to the
 `-c` argument of `metanorma collection` [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.7].
 +
 Any locally specified coverpage will be treated as a Liquid template, which can
 be populated with metadata extracted from the bibliographic metadata
 about the collection; refer to link:/develop/topics/metadata-and-boilerplate[Metadata and boilerplate].
 
-`collection-word-coverpage: ...`:::
+`collection-word-coverpage: {file-path}`:::
 Gives the location of the Word DOC coverpage for the entire
 collection [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].
 +
 If left out, or given as `null`, no such coverpage is added.
 
-`collection-word-intropage: ...`:::
+`collection-word-intropage: {file-path}`:::
 Gives the location of the Word DOC introductory section for the entire
 collection [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].
 +
@@ -144,14 +144,14 @@ boilerplate content, and a placeholder for the table of contents.
 +
 If left out, or given as `null`, no such introductory material is added.
 
-`document-word-coverpage: ...`:::
+`document-word-coverpage: {file-path}`:::
 Gives the location of the Word DOC coverpage for each individual
 document [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].
 +
 If left out, or given as `null`, the default cover page that would appear in a
 standalone document is used. If given as `""`, no such coverpage is added.
 
-`document-word-intropage: ...`:::
+`document-word-intropage: {file-path}`:::
 Gives the location of the DOC introductory section for each individual
 document [added in https://github.com/metanorma/metanorma/releases/tag/v1.7.5].
 +
@@ -180,6 +180,8 @@ cached for time savings [added in https://github.com/metanorma/metanorma/release
 `flavor`:::
 The flavor of Metanorma to use in processing the collection metadata and (by default)
 the documents it contains [added in https://github.com/metanorma/metanorma/releases/tag/v2.0.6].
+The corresponding value of `flavor` is described in the Metanorma document
+attribute `:mn-document-class:`.
 
 `format`::
 Specifies the possible output formats for the collection as a list,

author/topics/sections/attachments.adoc

@@ -4,13 +4,13 @@ title: Attachments
 ---
 == Purpose
 
-There are often occasions where a Metanorma document needs to hyperlink to
-separate files, that are not themselves Metanorma documents, but which need to
-be distributed together with the document.
+A Metanorma document can hyperlink to separate files that are distributed
+together with the document, even when they are not themselves Metanorma
+documents. These are called attachments.
 
-This could include source code, configuration files, executable binaries, or any
-other file -- so long as it is expected to be hyperlinked by Metanorma instead
-of being processed as a Metanorma file.
+Attachments could include source code, configuration files, executable binaries,
+or any other file -- so long as it is expected to be hyperlinked by Metanorma
+instead of being processed as a Metanorma file.
 
 == Syntax
 
@@ -19,17 +19,23 @@ File attachments are encoded in the bibliography section of a Metanorma document
 The syntax is provided as follows [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10]:
 
 [source,asciidoc]
---
-* [[[anchor,attachment:(file path of attachment relative to current fileidentifier)]]], attachment description
---
+----
+* [[[anchor,attachment:(file-path)]]], {attachment-desc}
+----
+
+Where:
+
+`file-path`:: the file location of the attachment relative to the current
+document root file.
 
-NOTE: Attachment description is needed for accessibility and conformance with PDF/A and PDF/UA.
+`attachment-desc`:: the description of the attachment.
++
+NOTE: Attachment description is needed for accessibility and required for
+conformance with PDF/A and PDF/UA.
 
-NOTE: The PDF attachments attributes _Volatile_ and _AFRelationship_ are realised through the syntax
-`span:classification.pdf-{Key}[{Value}]`, e.g. `span:classification.pdf-volatile[true]`,
-`span:classification.pdf-AFRelationship[EncryptedPayload]` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8].
 
 .Example of attaching the `schemas/schema.txt` file
+[example]
 ====
 This indicates that `schemas/schema.txt` is an attachment to the current
 document, and assigns the anchor `file1` to it.
@@ -43,11 +49,57 @@ Any cross-references to `<<file1>>` are to be interpreted as hyperlinks to that
 file, and will be so rendered in output.
 ====
 
+By default, attachments are base64-encoded within the output Metanorma XML file,
+just as with images.
+
+If the references to attachments are to be kept as file references in the XML
+file, set the document attribute `data-uri-attachment: false`.
+
+== PDF attachments
+
+PDF attachments can be embedded in the PDF output of a Metanorma document.
+
+PDF supports the following attributes for attachments:
+
+* _Volatile_: indicates that the attachment is volatile and should not be cached.
+
+* _AFRelationship_: indicates the relationship of the attachment to the document.
+
+NOTE: PDF attachment attributes are not supported in HTML output.
+ [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8].
+
+These attributes are realized in Metanorma through the bibliographic span
+syntax:
+
+[source,asciidoc]
+----
+... span:classification.pdf-{Key}[{Value}] ...
+----
+
+For _Volatile_, the syntax is `span:classification.pdf-volatile[true]`.
+
+For _AFRelationship_, the syntax is `span:classification.pdf-AFRelationship[EncryptedPayload]`.
+
+
+.Example of encoding a PDF attachment with attributes
+[example]
+====
+[source,adoc]
+----
+* [[[file1,attachment:(attachments/pdf-sample.pdf)]]],
+  span:surname[Wyatt], span:givenname[Peter],
+  span:date.issued[2021].
+  span:date[2021].
+  span:title[_Demystifying PDF through a machine-readable definition_].
+  In span:series[LangSec Workshop at IEEE Security & Privacy, May 27th and 28th, 2021].
+  span:publisher[IEEE].
+  span:uri.citation[https://langsec.org/spw21/papers.html#pdfReadable].
+  span:type[inproceedings]
+  span:classification.pdf-volatile[true]
+  span:classification.pdf-AFRelationship[EncryptedPayload]
+----
+====
 
-By default, attachments are binary-encoded within the Metanorma XML file, just
-as with images. If the references to attachments are to be kept as file
-references in the XML file, set the document attribute
-`data-uri-attachment: false`.
 
 == Output
 

author/topics/sections/bibliography.adoc

@@ -923,9 +923,12 @@ URI, of type _XXX_.
 Classification of bibliographic resource [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
 
 `classification.XXX`::
-Classification of bibliographic resource as being of type _XXX_ (e.g. `span:classification.color[red]`, 
-which is interpreted as "the bibliographic resource is classified as having color: 
-red") [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
+Classification of bibliographic resource as being of type _XXX_
+ [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
++
+[example]
+`span:classification.color[red]` can be interpreted as "the bibliographic
+resource is classified as having color: red".
 
 `abstract`::
 Abstract of bibliographic resource, can contain inline markup [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
@@ -947,9 +950,19 @@ The type is suppressed from rendering.
 [example]
 _standard_, _book_, _inbook_
 
-If spans are used, an inline image included in the reference is interpreted as the depiction
-of the resource [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8];
-e.g. `span:title[Standard 123] image:thumbnail.jpg[]`.
+If spans are used, an inline image included in the reference is interpreted as
+the depiction of the resource
+ [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.9.8]
++
+.An inline image in the reference as the depiction of the resource
+[example]
+====
+[source,adoc]
+----
+span:title[Standard 123] image:thumbnail.jpg[]
+----
+====
+
 
 NOTE: The surname must always precede the initials or given name for a given author in spans,
 to prevent ambiguity and confusion in parsing the reference.