-
Notifications
You must be signed in to change notification settings - Fork 8
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
user additions to boilerplate: metanorma/metanorma-iso#730
- Loading branch information
Showing
1 changed file
with
24 additions
and
103 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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,106 +440,16 @@ introductory page template; | |
| ** `<div id="boilerplate-license-destination"/>` 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] | ||
| ---- | ||
| <boilerplate> | ||
| <copyright-statement> | ||
| <clause> | ||
| <p>© {{ docyear }} Cloud Security Alliance, LLC.</p> | ||
| </clause> | ||
| </copyright-statement> | ||
| {% if unpublished %} | ||
| <license-statement> | ||
| <clause id="draft-warning"> | ||
| <title>Warning for Drafts</title> | ||
| <p>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. | ||
| </p> | ||
| </clause> | ||
| </license-statement> | ||
| {% endif %} | ||
| <legal-statement> | ||
| <clause> | ||
| <p>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. | ||
| </p> | ||
| </clause> | ||
| </legal-statement> | ||
| <feedback-statement> | ||
| <clause> | ||
| <p>Cloud Security Alliance</p> | ||
| <p align="left"> | ||
| 2212 Queen Anne Ave N<br /> | ||
| Seattle<br /> | ||
| WA 98109<br /> | ||
| United States of America<br /> | ||
| <br /> | ||
| <link target="mailto:[email protected]">[email protected]</link><br /> | ||
| <link target="www.cloudsecurityalliance.com">www.cloudsecurityalliance.com</link> | ||
| </p> | ||
| </clause> | ||
| </feedback-statement> | ||
| </boilerplate> | ||
| ---- | ||
|
|
||
| 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] | ||
| ---- | ||
| <boilerplate> | ||
| <license-statement/> | ||
| <legal-statement> | ||
| <clause> | ||
| <p>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. | ||
| </p> | ||
| </clause> | ||
| </legal-statement> | ||
| </boilerplate> | ||
| ---- | ||
|
|
||
| === 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 `<copyright-statement>`. | ||
| * The Asciidoctor is a Liquid template, just as for XML, so `{{ ... }}` is reserved for Liquid, and cannot | ||
| 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<br/>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:[email protected][[email protected]] | |
| 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 | ||
|
|
||