Prefatory clauses
Prefatory clauses
Prefatory sections are introductory sections that appear before the actual content is shown, for example, the “Foreword” section.
General
By default the single prefatory clause is identified with the pre-defined section titles:
-
Foreword
Foreword
A foreword is a full Metanorma AsciiDoc section, with the title “Foreword”; this can be overruled in different flavours. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] A foreword may contain subclauses.
[[foreword]]
== Foreword
The Calendaring and Scheduling Consortium ("`CalConnect`") is a global non-profit
organization with the aim to facilitate interoperability of technologies across
user-centric systems and applications...
=== Foreword subclause
More foreword...
Note
|
Metanorma AsciiDoc also supports a simple foreword clause syntax, using the AsciiDoc preamble (any text between the document header and the first section header). This syntax is restrictive (it requires there to be no preceding clauses and no subclauses), and is now deprecated. The example below specifies the Metanorma will supply the “Foreword” title if no such title is given.
|
Arbitrary prefatory clauses
Arbitrary prefatory clauses are allowed in some flavors, and are disallowed but “accepted” for encoding in certain flavors for backwards compatibility reasons.
Note
|
Most flavors specify requirements on preface sections. Most flavors specify mandatory and optional preface sections, while some completely disallow arbitrary preface sections. |
Any section detected as the following will be inserted into the document preface:
-
“Foreword”, or labelled as “Introduction”, “Acknowledgements” [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19]
-
“Executive summary” [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v3.0.7],
-
“Abstract”
-
Any other first-level clauses tagged with the role attribute
[.preface]
[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19].
If these prefatory sections are provided, they will be displayed in the following default ordering:
-
“Abstract”
-
“Foreword”
-
“Introduction”
-
Preface clauses. Any prefatory clauses that don’t fit the other specially “named” sections will be placed here.
-
“Acknowledgments”
-
“Executive summary”
This source:
// tagged as the "`abstract`"
[.preface,heading=abstract]
== Summary
Widget manufacture has proven profitable until recent times, when increased
competition has forced a reevaluation...
// tagged as the "`acknowledgements`"
[.preface,heading=acknowledgements]
== Organizational contributors
The following organizations have contributed valuable resources and expertise
for the completion of this standard...
// tagged as normal
[.preface]
== Note for draft
This is not an international standard, please be aware of the responsibilities
that come with application of this document...
Will be rendered in this order despite the input order:
-
“Summary”
-
“Note for draft”
-
“Acknowledgments”