Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

user additions to boilerplate: https://github.com/metanorma/metanorma… #832

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

user additions to boilerplate: https://github.com/metanorma/metanorma… #832

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
77fb073
user additions to boilerplate: https://github.com/metanorma/metanorma…
opoudjis Oct 19, 2024
b905b87
Japanese auto-numbering: https://github.com/metanorma/metanorma-jis/i…
opoudjis Oct 25, 2024
b6cd20b
coverpage images: https://github.com/metanorma/metanorma-jis/issues/227
opoudjis Oct 25, 2024
d85f407
Make mn- prefix in attributes optional; document them: https://github…
opoudjis Oct 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions author/jis/ref/document-attributes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
22 changes: 22 additions & 0 deletions author/ref/document-attributes.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -909,6 +925,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
Expand Down
127 changes: 24 additions & 103 deletions develop/topics/metadata-and-boilerplate.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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):

Expand All @@ -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:
Expand All @@ -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]
----
Expand Down Expand Up @@ -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]
----
Expand All @@ -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
Expand Down
Loading