From 5eee7acba3084a233edca0134566fe8ab7dfad18 Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Mon, 3 Jun 2024 23:15:52 +1000 Subject: [PATCH 1/6] attachments to Metanorma document: https://github.com/metanorma/metanorma-standoc/issues/709 --- _layouts/author-docs.html | 2 ++ author/ref/document-attributes.adoc | 7 +++++- author/topics/sections/attachments.adoc | 30 ++++++++++++++++++++++++ author/topics/sections/bibliography.adoc | 12 ++++++++++ 4 files changed, 50 insertions(+), 1 deletion(-) create mode 100644 author/topics/sections/attachments.adoc diff --git a/_layouts/author-docs.html b/_layouts/author-docs.html index 4ef4d6dd..3bd29879 100644 --- a/_layouts/author-docs.html +++ b/_layouts/author-docs.html @@ -66,6 +66,8 @@ path: /topics/sections/misc-container/ - title: Section attributes path: /topics/sections/attributes/ + - title: Attachments + path: /topics/sections/attachments/ - title: Blocks path: /topics/blocks/ diff --git a/author/ref/document-attributes.adoc b/author/ref/document-attributes.adoc index 04e1da12..c410e8d4 100644 --- a/author/ref/document-attributes.adoc +++ b/author/ref/document-attributes.adoc @@ -675,10 +675,15 @@ Defaults to value for built-in stylesheet. Overriding is not recommended. `:data-uri-image:`:: -Encode all images in HTML output as inline data-URIs. Defaults to `true`. +Encode all images in Metanorma XML and HTML output as inline data-URIs. Defaults to `true`. If not provided explicitly, is assumed to be `true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0]. +`:data-uri-attachments:`:: +Encode all attachments in Metanorma XML as inline data-URIs. Defaults to `true`. +If not provided explicitly, is assumed to be +`true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10]. + `:xrefstyle:`:: Override the default rendering of cross-references to clauses [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.6]. diff --git a/author/topics/sections/attachments.adoc b/author/topics/sections/attachments.adoc new file mode 100644 index 00000000..9f577bb4 --- /dev/null +++ b/author/topics/sections/attachments.adoc @@ -0,0 +1,30 @@ +--- +layout: author-docs +title: Attachments +--- +== Attachments + +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 with the document as local file references. +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. + +In order to signal to Metanorma that there are file attachments, the attachments need to be listed in the +bibliography of the Metanorma document, with the syntax [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)]]] +-- + +For example, the entry `* [[[file1,attachment:(schemas/schema.txt)]]]` indicates that schemas/schema.txt +is an attachment to the current document. It also indicates that any cross-references to `<>` are +to be interpreted as hyperlinks to that file, and will be so rendered in output. + +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`. + +When the Presentation XML output for a Metanorma document is generated (as a precursor to DOC, HTML and PDF output), +the documents are output to the folder `{document-filename}_attachments` relative to the output HTML file. + diff --git a/author/topics/sections/bibliography.adoc b/author/topics/sections/bibliography.adoc index 4d564177..971c1c04 100644 --- a/author/topics/sections/bibliography.adoc +++ b/author/topics/sections/bibliography.adoc @@ -647,6 +647,18 @@ cannot be used together. NOTE: Bibliographical information about the entry is *not* auto-fetched via Relaton. +=== Referencing an attachment + +Metanorma allows entries to specify file attachments, as described in +link:/author/topics/sections/attachments[Attachments] [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10]. + +This is achieved with the following syntax: + +[source,asciidoc] +-- +* [[[anchor,attachment:(file location of attachment relative to current file)]]] +-- + [[hyperlink-biblio]] === Referencing from Metanorma or Relaton files From a72650f62d9d3d7ee4b794c76dbd0295982fbf13 Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Mon, 3 Jun 2024 23:28:14 +1000 Subject: [PATCH 2/6] Hover anchor for clause headings in HTML: https://github.com/metanorma/metanorma-ogc/issues/659 --- author/topics/output/output-formats.adoc | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/author/topics/output/output-formats.adoc b/author/topics/output/output-formats.adoc index 8f36ee0f..731a176c 100644 --- a/author/topics/output/output-formats.adoc +++ b/author/topics/output/output-formats.adoc @@ -14,13 +14,19 @@ the link:/docs/authoring/validation[validation stage]. == HTML -The HTML output is in HTML 5. It has optional Data-URI encoding of local images; if images in the output are are not Data-URI encoded, +The HTML output is in HTML 5. It has optional Data-URI encoding of local images; if images in the output are not Data-URI encoded, they are moved to a folder called `{filename}_images`, and renamed with GUID names, to prevent collisions. Audio and video files are -not supported. All HTML output has a sidebar with a Javascript-generated Table of Contents, which is two section levels deep. +not supported. + +* All HTML output has a sidebar with a Table of Contents, which is two section levels deep. +* All clause headings have anchors which can be copied for hyperlinking. If the user hovers their mouse over a hyperlinked clause +heading, the section header glyph (§) appears, as with native Asciidoctor HTML output. If the user clicks on a hyperlinked clause +heading, the browser location bar will give the hyperlink with anchor for that clause [added in https://github.com/metanorma/isodoc/releases/tag/v2.10.3]. == PDF -Metanorma generates PDF output from XML. The styling comes from an https://www.xml.com/articles/2017/01/01/what-is-xsl-fo/[XSL-FO] stylesheet. Apache FOP interprets the stylesheet and generates the PDF. +Metanorma generates PDF output from XML. The styling comes from an https://www.xml.com/articles/2017/01/01/what-is-xsl-fo/[XSL-FO] stylesheet. +Apache FOP interprets the stylesheet and generates the PDF. For more information about how Apache FOP supports the XSL-FO standard, see the https://xmlgraphics.apache.org/fop/compliance.html[Apache FOP documentation]. From d6dd88b8362eca5bdc4f2a973ad6efc9823f49f8 Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Mon, 3 Jun 2024 23:29:00 +1000 Subject: [PATCH 3/6] Hover anchor for clause headings in HTML: https://github.com/metanorma/metanorma-ogc/issues/659 --- author/topics/output/output-formats.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/author/topics/output/output-formats.adoc b/author/topics/output/output-formats.adoc index 731a176c..b08c7310 100644 --- a/author/topics/output/output-formats.adoc +++ b/author/topics/output/output-formats.adoc @@ -19,7 +19,8 @@ they are moved to a folder called `{filename}_images`, and renamed with GUID nam not supported. * All HTML output has a sidebar with a Table of Contents, which is two section levels deep. -* All clause headings have anchors which can be copied for hyperlinking. If the user hovers their mouse over a hyperlinked clause +* All clause headings have anchors which can be copied for hyperlinking, and corresponding to the anchors provided by the author for +the clause (or failing that, a GUID based on a hash of the clause content). If the user hovers their mouse over a hyperlinked clause heading, the section header glyph (§) appears, as with native Asciidoctor HTML output. If the user clicks on a hyperlinked clause heading, the browser location bar will give the hyperlink with anchor for that clause [added in https://github.com/metanorma/isodoc/releases/tag/v2.10.3]. From 993f5fa933a835f9a6b9ad15fbbdc6b85ef53b38 Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Mon, 3 Jun 2024 23:49:08 +1000 Subject: [PATCH 4/6] Modspec requirement anchors: https://github.com/metanorma/metanorma-ogc/issues/663 --- .../topics/blocks/requirements-modspec.adoc | 20 ++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/author/topics/blocks/requirements-modspec.adoc b/author/topics/blocks/requirements-modspec.adoc index 524a4102..5f590648 100644 --- a/author/topics/blocks/requirements-modspec.adoc +++ b/author/topics/blocks/requirements-modspec.adoc @@ -331,6 +331,22 @@ requirement class that is being tested. Differentiated types of ModSpec models allow additional attributes. +`id` :: (optional) The Asciidoc `id` attribute assigns an anchor to the requirement, +as is the case with all blocks in Asciidoc (e.g. `id=idvalue`). The `id` attribute can also be expressed +as a block anchor (`[[idvalue]]`), or a hash attribute (`[#idvalue]`). The anchor is used in Metanorma +to write cross-references to elements (<>), +although we discuss below ways to use the Modspec `identifier` for such cross-references instead +(<>). ++ +If no anchor is provided, Metanorma will normally supply an anchor using a GUID derived from a hash of the +block's content. Modspec processing has been updated, so that if an identifier is provided, that is +used as the requirement anchor instead [added in https://github.com/metanorma/mn-requirements/releases/tag/v0.3.7]. +As with all XML anchors, illegal characters in the anchor (including `/`) are replaced with `_`. ++ +In order to enable easier hyperlinking of requireents, requirement headings are treated like clause headings +in HTML output [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.5.9]: a section mark glyph (§) +is displayed when the mouse is hovered over the requirement heading, and when the heading is clicked on, +the browser location bar displays the hyperlink with anchor to the requirement. [[generalreqt]] ==== Normative statement @@ -1116,6 +1132,7 @@ cross-reference, like `http://www.example.com/req/crs/crs-uri` instead of _Requirement Class 6_. ==== +[[predef-xref]] ==== Referencing using predefined anchors This can be extended to cross-references. If the anchor of the requirement is @@ -1136,6 +1153,7 @@ Requirement 10: `http://www.example.com/req/crs/crs-uri` ____ ==== +[[identifier-xref]] ==== Referencing using instance identifiers However, not all ModSpec instances are assigned predefined anchors, especially @@ -1162,7 +1180,7 @@ identifier:: http://www.example.com/req/crs/crs-uri ==== ---- ---- it is possible to reference a ModSpec instance using its identifier instead of +-- it is possible to reference a ModSpec instance using its identifier instead of the anchor, as follows. .Cross-reference to a ModSpec instance using its identifier, displaying the instance's name From 9818bee3e1714477d23dec461267e89ea010f9b2 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Tue, 18 Jun 2024 13:35:11 +0800 Subject: [PATCH 5/6] chore: update modspec id description --- .../topics/blocks/requirements-modspec.adoc | 67 +++++++++++++------ 1 file changed, 45 insertions(+), 22 deletions(-) diff --git a/author/topics/blocks/requirements-modspec.adoc b/author/topics/blocks/requirements-modspec.adoc index 5f590648..1b0bf48a 100644 --- a/author/topics/blocks/requirements-modspec.adoc +++ b/author/topics/blocks/requirements-modspec.adoc @@ -90,7 +90,8 @@ standardization target (an entity). ** A "`Conformance test`" is about a single standardization target. ** A "`Conformance test`" can be "`concrete`" or "`abstract`" depending on the -type of conformance test suite (see https://portal.ogc.org/files/?artifact_id=34762[OGC 08-131r3], 6.4). A concrete conformance test is typically called as a "`conformance test`", +type of conformance test suite (see https://portal.ogc.org/files/?artifact_id=34762[OGC 08-131r3], 6.4). +A concrete conformance test is typically called as a "`conformance test`", while an abstract conformance test is called an "`abstract test`". * A "`Test suite`" is "`a collection of identifiable conformance classes`" @@ -113,6 +114,19 @@ OGC standards that contain requirements must have those requirements conform to https://portal.ogc.org/files/?artifact_id=34762[OGC 08-131r3]. +=== Rendering + +Modspec instnace headings are treated like clause headings in HTML +output [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.5.9] +in order to enable easier hyperlinking of Modspec instances. + +* a section mark glyph (§) is displayed when the mouse is hovered over the +Modspec instance heading; + +* when the heading is clicked on, the browser location bar displays the +hyperlink with anchor to the Modspec instance. + + === Encoding syntax ==== General @@ -288,7 +302,8 @@ This is an OGC ModSpec requirement within an ISO document. ==== Instance attributes -Attributes accepted by a ModSpec instance are as follows: +Attributes accepted by a ModSpec instance are as follows. +Differentiated types of ModSpec models allow additional attributes. `identifier`:: (mandatory) Identifier of the requirement, such as a URI or a URN. Plain text. @@ -329,24 +344,31 @@ requirement class that is being tested. // * `model` (optional when using Metanorma OGC). Type of model. The value of `ogc` // means using OGC ModSpec models. -Differentiated types of ModSpec models allow additional attributes. - -`id` :: (optional) The Asciidoc `id` attribute assigns an anchor to the requirement, -as is the case with all blocks in Asciidoc (e.g. `id=idvalue`). The `id` attribute can also be expressed -as a block anchor (`[[idvalue]]`), or a hash attribute (`[#idvalue]`). The anchor is used in Metanorma -to write cross-references to elements (<>), -although we discuss below ways to use the Modspec `identifier` for such cross-references instead -(<>). +`id`:: + -If no anchor is provided, Metanorma will normally supply an anchor using a GUID derived from a hash of the -block's content. Modspec processing has been updated, so that if an identifier is provided, that is -used as the requirement anchor instead [added in https://github.com/metanorma/mn-requirements/releases/tag/v0.3.7]. -As with all XML anchors, illegal characters in the anchor (including `/`) are replaced with `_`. -+ -In order to enable easier hyperlinking of requireents, requirement headings are treated like clause headings -in HTML output [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.5.9]: a section mark glyph (§) -is displayed when the mouse is hovered over the requirement heading, and when the heading is clicked on, -the browser location bar displays the hyperlink with anchor to the requirement. +-- +(optional) Predefined anchor of the requirement. + +By default: + +* If `identifier` is provided, it is set identically to the +`identifier` [added in https://github.com/metanorma/mn-requirements/releases/tag/v0.3.7]. +* Otherwise, it is set to a generated GUID that is derived from a hash of its +content. + +The predefined anchor is used in Metanorma for <> +though the Modspec `identifier` is the recommended method for <>. + +This attribute can also be expressed as: + +* block anchor: `\[[idvalue]]` +* hash attribute: `[#idvalue]` +-- + +Accepted values::: Same as XML IDs. Unaccepted characters (including `/`) are +replaced with `_`. + + [[generalreqt]] ==== Normative statement @@ -1156,8 +1178,9 @@ ____ [[identifier-xref]] ==== Referencing using instance identifiers -However, not all ModSpec instances are assigned predefined anchors, especially +Not all ModSpec instances are assigned predefined anchors, especially when using model-based generation. + It also precludes automated manipulation of the identifier base path. For that reason, Modspec in Metanorma supports @@ -1255,10 +1278,10 @@ Renders as: This will also highlight the URI text as subject to truncation, with reference to identifier bases. -In some flavours (ISO as of this writing), the automatically generated cross-references +In some flavours (ISO as of this writing), the automatically generated cross-references within requirements (listings of provisions, tests, child and parent requirements) is different from the default rendering of cross-references in documents. In order to use the same -cross-reference style as occurs inside of requirements, you can specify +cross-reference style as occurs inside of requirements, you can specify `style=modspec%` [added in https://github.com/metanorma/mn-requirements/releases/tag/v0.3.1]. For example, in ISO, in the main body of text From ad1212713c539e8b234852da4f491bee30f624f0 Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Tue, 18 Jun 2024 14:04:31 +0800 Subject: [PATCH 6/6] chore: clean up bib and attachments --- author/ref/document-attributes.adoc | 10 +- .../topics/blocks/requirements-modspec.adoc | 92 ++++++++++--------- author/topics/sections/attachments.adoc | 60 +++++++++--- author/topics/sections/bibliography.adoc | 35 ++++--- 4 files changed, 121 insertions(+), 76 deletions(-) diff --git a/author/ref/document-attributes.adoc b/author/ref/document-attributes.adoc index c410e8d4..50451416 100644 --- a/author/ref/document-attributes.adoc +++ b/author/ref/document-attributes.adoc @@ -675,14 +675,12 @@ Defaults to value for built-in stylesheet. Overriding is not recommended. `:data-uri-image:`:: -Encode all images in Metanorma XML and HTML output as inline data-URIs. Defaults to `true`. -If not provided explicitly, is assumed to be -`true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0]. +Encode all images in Metanorma XML and HTML output as inline data-URIs. +Defaults to `true`. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.0]. `:data-uri-attachments:`:: -Encode all attachments in Metanorma XML as inline data-URIs. Defaults to `true`. -If not provided explicitly, is assumed to be -`true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10]. +Encode all attachments in Metanorma XML as inline data-URIs. +Defaults to `true`. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10]. `:xrefstyle:`:: Override the default rendering of cross-references to diff --git a/author/topics/blocks/requirements-modspec.adoc b/author/topics/blocks/requirements-modspec.adoc index 1b0bf48a..4fcfc273 100644 --- a/author/topics/blocks/requirements-modspec.adoc +++ b/author/topics/blocks/requirements-modspec.adoc @@ -1143,9 +1143,12 @@ https://tools.ietf.org/html/rfc3986#section-3[RFC 3986, section 3]. ==== General -Similar to when specifying attributes for ModSpec instances, it is preferred to refer -to other instances using identifiers, rather than the numbered labels allocated -by default. +Similar to when specifying attributes for ModSpec instances, it is preferred to +refer to other instances using identifiers, rather than the numbered labels +allocated by default. + +Metanorma treats both cross-referncing mechanisms as fully equivalent, and will +render them in the same way, as a numbered label (_Requirement Class 6_). [example] ==== @@ -1154,45 +1157,35 @@ cross-reference, like `http://www.example.com/req/crs/crs-uri` instead of _Requirement Class 6_. ==== -[[predef-xref]] -==== Referencing using predefined anchors - -This can be extended to cross-references. If the anchor of the requirement is -known, a normal cross-reference can be marked up, as shown below. - -.Cross-reference to a ModSpec instance using a predefined anchor -[example] -==== -[source,adoc] ----- -<> ----- - -Renders (assuming that this is the 10th Requirement): - -____ -Requirement 10: `http://www.example.com/req/crs/crs-uri` -____ -==== - [[identifier-xref]] ==== Referencing using instance identifiers -Not all ModSpec instances are assigned predefined anchors, especially -when using model-based generation. - -It also precludes automated manipulation of the identifier base path. - -For that reason, Modspec in Metanorma supports +Modspec in Metanorma supports link:/author/topics/document-format/xrefs/#anchor-aliasing[anchor aliasing]: the identifier of the requirement can be used in cross-references as an alias of the anchor. +This is the preferred method to cross-reference Modspec instances, through its +identifier instead of the predefined anchor. + +[NOTE] +-- +This is due to the following reasons: + +* not all ModSpec instances are assigned predefined anchors, especially when +using model-based generation. +* using predefined anchors precludes automated manipulation of the identifier +base path. +-- + Metanorma will automatically map the anchor it allocates to requirements to -identifiers, to that end: users do not need to supply the anchor alias mappings +identifiers, so users do not need to supply the anchor alias mappings manually. -So for a requirement such as: +.Cross-reference to a ModSpec instance using its identifier, displaying the instance's name +[example] +===== +For a requirement such as: [source,adoc] ---- @@ -1203,12 +1196,8 @@ identifier:: http://www.example.com/req/crs/crs-uri ==== ---- --- it is possible to reference a ModSpec instance using its identifier instead of -the anchor, as follows. +The following cross-reference: -.Cross-reference to a ModSpec instance using its identifier, displaying the instance's name -[example] -==== [source,adoc] ---- xref:http://www.example.com/req/crs/crs-uri[] @@ -1219,14 +1208,33 @@ Renders (assuming that this is the 10th Requirement): ____ Requirement 10: `http://www.example.com/req/crs/crs-uri` ____ -==== - -Metanorma treats them as fully equivalent, and will render them in the same way, -as a numbered label (_Requirement Class 6_). +===== NOTE: As a limitation of syntax, URIs cannot be processed correctly within `<<..>>`. The `xref:...[]` command needs to be used instead. + +[[predef-xref]] +==== Referencing using predefined anchors + +The anchor of the requirement can be used in a normal cross-reference. + +.Cross-reference to a ModSpec instance using a predefined anchor +[example] +==== +[source,adoc] +---- +<> +---- + +Renders (assuming that this is the 10th Requirement): + +____ +Requirement 10: `http://www.example.com/req/crs/crs-uri` +____ +==== + + ==== Cross-reference rendering Following Modspec practice, all cross-references to Modspec instances from within another @@ -1234,7 +1242,7 @@ Modspec instance are rendered along with the URI identifier of that instance where available; the URI is truncated with reference to an identifier base (see <>). -So a reference to `<>` or to `xref:http://www.example.com/req/crs/crs-uri[]` made within +So a reference to `<>` or to `xref:http://www.example.com/req/crs/crs-uri[]` made within a Modspec instance will render as ____ diff --git a/author/topics/sections/attachments.adoc b/author/topics/sections/attachments.adoc index 9f577bb4..d82e1280 100644 --- a/author/topics/sections/attachments.adoc +++ b/author/topics/sections/attachments.adoc @@ -2,29 +2,61 @@ layout: author-docs title: Attachments --- -== 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 with the document as local file references. -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. +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. -In order to signal to Metanorma that there are file attachments, the attachments need to be listed in the -bibliography of the Metanorma document, with the syntax [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10]: +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. + +== Syntax + +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)]]] -- -For example, the entry `* [[[file1,attachment:(schemas/schema.txt)]]]` indicates that schemas/schema.txt -is an attachment to the current document. It also indicates that any cross-references to `<>` are -to be interpreted as hyperlinks to that file, and will be so rendered in output. +.Example of attaching the `schemas/schema.txt` file +==== +This indicates that `schemas/schema.txt` is an attachment to the current +document, and assigns the anchor `file1` to it. + +[source,adoc] +---- +* [[[file1,attachment:(schemas/schema.txt)]]] +---- + +Any cross-references to `<>` are to be interpreted as hyperlinks to that +file, and will be so rendered in output. +==== + -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 +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`. -When the Presentation XML output for a Metanorma document is generated (as a precursor to DOC, HTML and PDF output), -the documents are output to the folder `{document-filename}_attachments` relative to the output HTML file. +== Output + +=== General + +When the Presentation XML output for a Metanorma document is generated (as a +precursor to DOC, HTML and PDF output), the documents are output to the folder +`{document-filename}_attachments` relative to the output HTML file. + +=== HTML + +In HTML, references to the attachments are hyperlinked from the bibliography to +their disk location. + +=== PDF +In PDF, attachments are embedded in the PDF can be saved from the PDF file +when using a compatible PDF reader. diff --git a/author/topics/sections/bibliography.adoc b/author/topics/sections/bibliography.adoc index 971c1c04..f1fb4050 100644 --- a/author/topics/sections/bibliography.adoc +++ b/author/topics/sections/bibliography.adoc @@ -133,7 +133,7 @@ See link:/author/ietf/topics/references/[References (AsciiRFC v3)] for further details. ==== -=== Numbering and ordering +== Numbering and ordering All entries in a bibliography section, whether standards or generic, are renumbered incrementally in the Metanorma XML. If the number for @@ -150,7 +150,7 @@ even if there is intervening text in the source document. Only notes are left attached to their reference, in order to enable annotated bibliographies. -=== Predefined text +== Predefined text Any initial text in a Normative Reference section (before the first reference) is replaced by predefined text specific to the Metanorma flavour. @@ -174,8 +174,6 @@ document. == Entering individual references -=== General - Bibliographic entries are entered as unordered lists in Metanorma AsciiDoc within a dedicated clause or section. @@ -219,21 +217,26 @@ If encoded in the ISO 690:2021 format, the resulting citation will be a machine-readable one. -=== Types of references +== Best practice -There are multiple ways of entering bibliographic items in Metanorma for -referencing as shown in <>. +There are myriad ways of entering bibliographic references as shown in +<>. -The most commonly-used methods are: +As best practice, we recommend the following order of entering bibliographic +references, only using a later method if the former method does not: + +. <> +.. <> +.. <> +.. <> +. Manual encoding +.. <> +.. <> +.. <> -* <>; -* <>; -* <>; and -* <>. It is strongly recommended that the <> method be -used for data consistency and ease of use whenever possible (especially for -references to standards supported by Relaton). +used for data consistency, correctness, and the ease of use whenever possible. If automatic fetching is not available for a particular reference, and if machine-readability or accurate rendering is important, either @@ -489,6 +492,7 @@ The fetched data overrides any content about the item provided in the document, since the online bibliography is treated as the source of truth for that standards document. +[[auto-pubid-lookup]] ==== Standards identifier / Document identifier lookup The format of the standard identifier required for automatic lookup is documented at @@ -514,6 +518,7 @@ ISO 20483:2013. _Cereals and cereal products -- Determination of moisture conten ____ ==== +[[auto-crossref-lookup]] ==== DOI identifier lookup DOI identifiers are supported as auto-fetch targets [added in @@ -546,6 +551,7 @@ Massart D., Shulman E., Nicholas N., Ward N., & Bergeron F. Taming the Meta ____ ==== +[[auto-isbn-lookup]] ==== ISBN identifier lookup ISBN identifiers are supported as auto-fetch targets [added in @@ -659,6 +665,7 @@ This is achieved with the following syntax: * [[[anchor,attachment:(file location of attachment relative to current file)]]] -- + [[hyperlink-biblio]] === Referencing from Metanorma or Relaton files