attachments to Metanorma document: https://github.com/metanorma/metan…

_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/

author/ref/document-attributes.adoc

@@ -675,9 +675,12 @@ 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`.
-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`. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.10].
 
 `:xrefstyle:`::
 Override the default rendering of cross-references to

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,7 +344,30 @@ 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) 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 <<predef-xref,element referencing>>
+though the Modspec `identifier` is the recommended method for <<identifier-xref,referencing of requirements>>.
+
+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]]
@@ -1105,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]
 ====
@@ -1116,42 +1157,35 @@ cross-reference, like `http://www.example.com/req/crs/crs-uri` instead of
 _Requirement Class 6_.
 ====
 
-==== 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]
-----
-<<id1,http://www.example.com/req/crs/crs-uri>>
-----
-
-Renders (assuming that this is the 10th Requirement):
-
-____
-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
-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]
 ----
@@ -1162,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[]
@@ -1178,22 +1208,41 @@ 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]
+----
+<<id1,http://www.example.com/req/crs/crs-uri>>
+----
+
+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
 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 <<identifier-base>>).
 
-So a reference to  `<<id1>>` or to `xref:http://www.example.com/req/crs/crs-uri[]` made within
+So a reference to `<<id1>>` or to `xref:http://www.example.com/req/crs/crs-uri[]` made within
 a Modspec instance will render as
 
 ____
@@ -1237,10 +1286,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

author/topics/output/output-formats.adoc

@@ -14,13 +14,20 @@ 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, 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].
 
 == 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].
 

author/topics/sections/attachments.adoc

@@ -0,0 +1,62 @@
+---
+layout: author-docs
+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.
+
+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)]]]
+--
+
+.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 `<<file1>>` 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`.
+
+== 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.