From 77fb0730cba7aee85b3de0e67fa332cfa2c83a66 Mon Sep 17 00:00:00 2001 From: Nick Nicholas Date: Sat, 19 Oct 2024 16:16:05 +1100 Subject: [PATCH] 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