From f88d396916cdb2b57794c1a1f18fac150b71407e Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Tue, 15 Oct 2024 17:15:12 +0800 Subject: [PATCH] chore: update documentation --- author/topics/collections/configuration.adoc | 12 +-- author/topics/sections/attachments.adoc | 86 ++++++++++++++++---- author/topics/sections/bibliography.adoc | 25 ++++-- 3 files changed, 95 insertions(+), 28 deletions(-) diff --git a/author/topics/collections/configuration.adoc b/author/topics/collections/configuration.adoc index 104bd053..d35f1695 100644 --- a/author/topics/collections/configuration.adoc +++ b/author/topics/collections/configuration.adoc @@ -120,7 +120,7 @@ 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]. + @@ -128,13 +128,13 @@ 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, diff --git a/author/topics/sections/attachments.adoc b/author/topics/sections/attachments.adoc index ab3aa7c2..6d4b0a02 100644 --- a/author/topics/sections/attachments.adoc +++ b/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 `<>` 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 diff --git a/author/topics/sections/bibliography.adoc b/author/topics/sections/bibliography.adoc index 7c1df9b0..fe82acf3 100644 --- a/author/topics/sections/bibliography.adoc +++ b/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.