From 77fb0730cba7aee85b3de0e67fa332cfa2c83a66 Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Sat, 19 Oct 2024 16:16:05 +1100 Subject: [PATCH 1/4] user additions to boilerplate: https://github.com/metanorma/metanorma-iso/issues/730 --- develop/topics/metadata-and-boilerplate.adoc | 127 ++++--------------- 1 file changed, 24 insertions(+), 103 deletions(-) diff --git a/develop/topics/metadata-and-boilerplate.adoc b/develop/topics/metadata-and-boilerplate.adoc index 128ead02..3c197bbb 100644 --- a/develop/topics/metadata-and-boilerplate.adoc +++ b/develop/topics/metadata-and-boilerplate.adoc @@ -390,9 +390,7 @@ or not depends on the value of `bibdata/status`.) [[boilerplate]] == Predefined text -=== XML - -The `boilerplate` element in Metanorma XML follows after `bibdata`, and +The `boilerplate` element in Metanorma Asciidoc follows after `bibdata`, and contains text that is repeatedly included in each instance of the document class, and that outlines the rules under which the document may be used. @@ -409,15 +407,15 @@ a title, multiple paragraphs, and subclauses. Because the predefined text is repeated for each document in its class, it is not expected to be supplied by the user (although the user can supply their own predefined text file using the `:boilerplate-authority:` document attribute). -Instead, the predefined text is included as a Metanorma XML file within the gem; by default, it is called -`boilerplate.xml`. +Instead, the predefined text is included as a Metanorma Asciidctor file within the gem; by default, it is called +`boilerplate.adoc`. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.6] -Some of the predefined text may be populate with metadata specific to the current document, +Some of the predefined text may be populated with metadata specific to the current document, so the predefined text file is a Liquid template, populated with variables from the current flavour metadata Hash as with other templated text. The content in the `boilerplate` element is processed as part of the document preface, and converted to HTML or -Word like the rest of the Metanorma XML. However, predefined text usually ends up in the cover page or +Word like the rest of the Metanorma source text. However, predefined text usually ends up in the cover page or introductory page of the document instead. The following are the default conventions in Metanorma, although they can be overridden in the `IsoDoc::*::Converter.authority_cleanup` method (as is currently done in NIST): @@ -442,91 +440,7 @@ introductory page template; ** `
` appears in the title page template for the flavour; ** the CSS styling for the front page draft warning is styled as `boilerplate-license`. -A user-supplied boilerplate file need not provide all four statements [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.2]. -If the user-supplied element is missing an element in the default for the flavour, the default is retained. -If the element is to be deleted, provide it as an empty title. - -The following predefined text from metanorma-csa exemplifies all four statements in a predefined text, -and its processing as a Liquid template. - -[source,xml] ----- - - - -

© {{ docyear }} Cloud Security Alliance, LLC.

- - - - {% if unpublished %} - - - Warning for Drafts - -

This document is not a CSA Standard. It is distributed for review and - comment, and is subject to change without notice and may not be referred to as - a Standard. Recipients of this draft are invited to submit, with their - comments, notification of any relevant patent rights of which they are aware - and to provide supporting documentation. -

- - - {% endif %} - - - -

All rights reserved. Unless otherwise specified, no part of this - publication may be reproduced or utilized otherwise in any form or by any - means, electronic or mechanical, including photocopying, or posting on the - internet or an intranet, without prior written permission. Permission can - be requested from the address below. -

- - - - - -

Cloud Security Alliance

-

- 2212 Queen Anne Ave N
- Seattle
- WA 98109
- United States of America
-
- copyright@cloudsecurityalliance.com
- www.cloudsecurityalliance.com -

- - - ----- - -The following user-provided predefined text will delete the license statement, and override the legal statement, -leaving the copyright statement and feedback statement of the flavour alone: - -[source,xml] ----- - - - - - -

All rights reserved. Unless otherwise specified, no part of this - publication may be reproduced or utilized otherwise in any form or by any - means, electronic or mechanical, including photocopying, or posting on the - internet or an intranet, without prior written permission. Permission can - be requested from the address below. -

- - - ----- - -=== ADOC - -Predefined text can also be specified in Metanorma Asciidoc, with the file suffix `.adoc` -[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.6]. The following special -processing rules apply: +The following special processing rules apply for Asciidoctor input: * Top-level clauses ending in `-statement` are converted into the equivalent `boilerplate` tags; so `== copyright-statement` corresponds to Metanorma XML ``. @@ -534,14 +448,8 @@ processing rules apply: be used for Metanorma AsciiDoc concepts. The AsciiDoc is processed by Liquid before it is passed on for processing. * Clauses in predefined text often do not have clause titles; as usual for Asciidoc, introduce such titles with `=== {blank}`. -* Clauses in Asciidoctor with no title and no user-assigned anchor are automatically assigned an anchor -of the form `_{n}`, where `{n}` is an integer. In order to prevent those anchors colliding in the boilerplate and -the main document, we overwrite any such anchors in the predefined text with the normal Metanorma default, -`_` followed by a GUID. Do not use `_{n}` as an anchor in any of your predefined text. -* Also be on the lookout -for any clauses with identical titles in your predefined text and your main document; if no user-defined anchor -is supplied, they will end up with the same title. To prevent that, the simplest thing to do is to provide -user-defined anchors for all titled clauses in the predefined text. +* Clauses in the Asciidoctor boilerplate with no user-assigned anchor are automatically assigned an anchor +of the form `_{n}`, where `{n}` is a GUID. * The values that populate Liquid templates in Metanorma are in Metanorma XML, if they contain any formatting; Metanorma automatically treats AsciiDoc Liquid variables as Metanorma XML passthrough values. For example, the `pub-address` document variable may be specified as document attribute as: @@ -557,9 +465,14 @@ But its value in Liquid will be `1 John St
London`, since Liquid interpolati Metanorma will treat any instance of `{{ pub_address}}` in AsciiDoc predefined text as `pass:[{{pub_address}]` (i.e. when converting the AsciiDoc predefined text to Metanorma XML, the contents of `{{pub_address}}` will be left alone.) -- +* A user-supplied boilerplate file need not provide all four statements [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.2]. +If the user-supplied element is missing an element in the default for the flavour, the default is retained. +If the element is to be deleted, provide it as an empty title. +* Text can be appended to the default boilerplate [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.10.0]. +This is done by specifying the top-level clause as `== copyright-statement-append`, `== license-statement-append`, etc. -The following is the Asciidoctor equivalent of the `boilerplate` Metanorma XML just given. This is for -a complete boilerplate document: +The following predefined text from metanorma-csa exemplifies all four statements in a predefined text, +and its processing as a Liquid template. [source,adoc] ---- @@ -601,7 +514,8 @@ mailto:copyright@cloudsecurityalliance.com[copyright@cloudsecurityalliance.com] https://www.cloudsecurityalliance.com[www.cloudsecurityalliance.com] ---- -And this will do a partial update, as above: +The following user-provided predefined text will delete the license statement, override the legal statement, +leaving the copyright statement of the flavour alone, and append to the flavour's feedback statement: [source,adoc] ---- @@ -614,6 +528,13 @@ publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from the address below. + +== feedback-statement-append + +[[feedback-addition]] +=== {blank} +Check with your supplier for local information. + ---- == Cover page notes From b905b8722205b74d5335444806dcd06e6ce1152d Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Sat, 26 Oct 2024 00:48:32 +1100 Subject: [PATCH 2/4] Japanese auto-numbering: https://github.com/metanorma/metanorma-jis/issues/228 --- author/jis/ref/document-attributes.adoc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/author/jis/ref/document-attributes.adoc b/author/jis/ref/document-attributes.adoc index e3e7c039..e950dd8f 100644 --- a/author/jis/ref/document-attributes.adoc +++ b/author/jis/ref/document-attributes.adoc @@ -493,3 +493,10 @@ Email of personal author for this document (for document type `expert-commentary `:role_{i}:`:: Role of personal author for this document (for document type `expert-commentary` only) (default: `author`) + +== Document presentation + +`:presentation-metadata-autonumbering-style:` What numbering style to apply to automatically generated text +containing numbers [added in https://github.com/metanorma/metanorma-jis/releases/tag/v0.3.7]. +Applies to edition numbers, Japanese dates, clause numbers, and ordered list numbers (in PDF). +Allowed values are `arabic` (default) and `japanese`. From b6cd20b3aa0363ba1db4470f1745a36b09a0325a Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Sat, 26 Oct 2024 01:01:17 +1100 Subject: [PATCH 3/4] coverpage images: https://github.com/metanorma/metanorma-jis/issues/227 --- author/ref/document-attributes.adoc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/author/ref/document-attributes.adoc b/author/ref/document-attributes.adoc index c8c073a6..3c7da9b0 100644 --- a/author/ref/document-attributes.adoc +++ b/author/ref/document-attributes.adoc @@ -909,6 +909,12 @@ A comma-delimited list of Metanorma block names, which should have numbering suppressed throughout the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.6]. Typically will be used for sourcecode fragemnts: `:block-unnumbered: sourcecode`. +`:coverpage-image:`:: Comma-delimited list of image locations, for images to be included on the (PDF) cover page. All image locations are relative to the source document. Currently only supported for BSI, ITU, JIS, Plateau. +`:innercoverpage-image:`:: Same, for images to be included on the (PDF) inside cover page. Currently only supported for BSI. +`:tocside-image:`:: Same, for images to be included on the (PDF) Table of Contents side page. Currently only supported for BSI. +`:backpage-image:`:: Same, for images to be included on the (PDF) back page. Currently only supported for BSI, JIS. + + == PDF protection and permissions All the following attributes relate to protection of PDF files as described From d85f4074cd98741e29224b573c74a8a6fd0b34a6 Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Sat, 26 Oct 2024 20:23:55 +1100 Subject: [PATCH 4/4] Make mn- prefix in attributes optional; document them: https://github.com/metanorma/metanorma/issues/421 --- author/ref/document-attributes.adoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/author/ref/document-attributes.adoc b/author/ref/document-attributes.adoc index 3c7da9b0..956dc8f5 100644 --- a/author/ref/document-attributes.adoc +++ b/author/ref/document-attributes.adoc @@ -14,6 +14,22 @@ required document attributes. == Build and validation +`:mn-document-class:`:: +The flavor of Metanorma used to compile the document; e.g. `iso`, `nist`, `ogc`. Needs to be a supported version +of the document. Synonyms: `document-class`, `mn-flavor`, `flavor`. + +`:mn-output-extensions:`:: +The output formats to generate for the document, comma-delimited; e.g. `xml,presentation,html,doc,pdf`. +The formats supported vary for each flavor, but all flavors support `xml` (Semantic XML), `presentation` +(Presentation XML), and one of `html` or `pdf`. Synonym: `:output-extensions:`. + +`:mn-relaton-output-file:`:: +Output the bibliographic record describing the document as a Relaton XML file (with the suffix `.rxl`). +Synonym: `:relaton-output-file:`. + +`:mn-keep-asciimath:`:: +Do not translate Asciimath in the document to MathML. Synonym: `:keep-asciimath:`. + `:nodoc:`:: Instructs Metanorma to not generate Word and HTML output, means only XML output will be generated.