summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/metanorma/metanorma.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/metanorma/metanorma.adoc')
-rw-r--r--macros/latex/contrib/metanorma/metanorma.adoc1650
1 files changed, 1650 insertions, 0 deletions
diff --git a/macros/latex/contrib/metanorma/metanorma.adoc b/macros/latex/contrib/metanorma/metanorma.adoc
new file mode 100644
index 0000000000..83dd1c9aa3
--- /dev/null
+++ b/macros/latex/contrib/metanorma/metanorma.adoc
@@ -0,0 +1,1650 @@
+//
+// tex2mn 0.5.0 - converts Metanorma documents from LaTeX to AsciiDoc
+//
+// Copyright (C) 2019-2020 Ribose Inc. <open.source@ribose.com>
+// This project is available under the terms of the MIT License.
+//
+
+= tex2mn manual
+:epoch: 1574615272
+:ctan-pkg-url: https://ctan.org/pkg
+:repo-url: https://github.com/metanorma/tex2mn
+:repo-tag: master
+:repo-blob-url: {repo-url}/blob/{repo-tag}
+:repo-tree-url: {repo-url}/tree/{repo-tag}
+:toc:
+:toclevels: 5
+
+:leveloffset: +1
+
+= Reading the manual
+
+Since `tex2mn` is a tool to transform `LaTeX` source files, some familiarity with `LaTeX` and its de-facto standard packages is assumed.
+
+We will graphically differentiate between:
+
+* `\standard` well-known macros which have standard behaviour, and
+* `*\NonStandard*` macros which are unique to `tex2mn` and will be documented thoroughly.
+
+[NOTE]
+====
+In either case we will point out which `LaTeX` packages are used to define them (if any).
+====
+
+Code samples will _always_ be presented as pairs of equivalent `LaTeX`/`AsciiDoc` listings to help you acquaint with both regardless of which side you're more familiar with:
+
+[cols="5a,4a"]
+|===
+|[source,latex]
+----
+What a \textbf{bold} statement.
+----
+|[source,asciidoc]
+----
+What a *bold* statement.
+----
+|===
+
+That's it.
+You can confidently start reading, now!
+
+If you happen to find any unexpected behaviour in the software or lack of clarity in the manual, please report it on our {repo-url}/issues[issue tracker] to help us make this tool better for everyone.
+
+:leveloffset!:
+
+== Document
+:leveloffset: +2
+
+= Document title
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_title.rb[test_title.rb].
+
+You can define the document's title by using the `\title` macro _in the preamble_:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+\title{My first document}
+\begin{document}
+ Document contents here.
+\end{document}
+----
+|[source,asciidoc]
+----
+= My first document
+
+Document contents here.
+----
+|===
+
+:leveloffset!:
+:leveloffset: +2
+
+= Document attributes
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_document_attributes.rb[test_document_attributes.rb].
+
+Document attributes are global metadata that can be interpreted by `metanorma` when processing the `AsciiDoc` output.
+Which attributes you should use depend upon the Metanorma flavour you're targeting.
+Attributes supported by most Metanorma flavours can be found in the https://www.metanorma.com/author/ref/document-attributes/[generic attributes reference].
+
+You can define a document attribute by using the `*\set*` macro _in the preamble_:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+\set{my-attribute}{foobar}
+\begin{document}
+ Document contents here.
+\end{document}
+----
+|[source,asciidoc]
+----
+:my-attribute: foobar
+
+Document contents here.
+----
+|===
+
+You can define a boolean attribute by using the `*\set*` with an empty argument:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+\set{my-boolean-attribute}{}
+\begin{document}
+ Document contents here.
+\end{document}
+----
+|[source,asciidoc]
+----
+:my-boolean-attribute:
+
+Document contents here.
+----
+|===
+
+
+You can use an attribute's value by using the `*\get*` macro:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+\set{my-attribute}{some value}
+\begin{document}
+ The attribute value is \get{my-attribute}.
+\end{document}
+----
+|[source,asciidoc]
+----
+:my-attribute: some value
+
+The attribute's value is {my-attribute}.
+----
+|===
+
+:leveloffset!:
+:leveloffset: +2
+
+= Document authors
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_document_authors.rb[test_document_authors.rb].
+
+Document authors are handled as document attributes.
+
+You can `*\set*` a single author by specifying it in the preamble:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+\set{author}{John Doe}
+\begin{document}
+ Document authored by \get{author}.
+\end{document}
+----
+|[source,asciidoc]
+----
+:author: John Doe
+
+Document authored by {author}.
+----
+|===
+
+You can `*\set*` a multiple authors by enumerating them in the preamble:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+\set{author_1}{Tom Sawyer}
+\set{author_2}{Dick Tracy}
+\set{author_3}{Harry Potter}
+\begin{document}
+ Document authored by \get{author_1}, \get{author_2}, and \get{author_3}.
+\end{document}
+----
+|[source,asciidoc]
+----
+:author_1: Tom Sawyer
+:author_2: Dick Tracy
+:author_3: Harry Potter
+
+Document authored by {author_1}, {author_2}, and {author_3}.
+----
+|===
+
+:leveloffset!:
+
+== `*\mn*`: TODO
+
+:leveloffset: +1
+
+= Sections
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_headings.rb[test_headings.rb].
+
+You can perform sectioning with the usual hierarchy of macros: `\section`, `\subsection`, `\subsubsection`, `\paragraph`, and `\subparagraph`:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{My section}
+
+\subsection{My subsection}
+
+\subsubsection{My subsubsection}
+
+\paragraph{My paragraph}
+
+\subparagraph{My subparagraph}
+----
+|[source,asciidoc]
+----
+== My section
+
+=== My subsection
+
+==== My subsubsection
+
+===== My paragraph
+
+====== My subparagraph
+----
+|===
+
+
+
+
+== Fixed names
+
+Metanorma relies on (case insensitive) canonical names to recognize a few standard sections:
+
+* `Abstract`
+* `Introduction`
+* `Scope`
+* `Normative References`
+* `Terms and Definitions`
+* `Symbols and Abbreviations`
+* `Bibliography`
+
+NOTE: `Terms and Definitions` and `Symbols and Abbreviations` expect a fixed structure, explained in the respective sections of this manual. Conversely, the heading for `Bibliography` is tipically generated automatically.
+
+If you need to name these sections in a different way (e.g. in non-english documents), you can set the canonical name to be recognized by Metanorma as an attribute:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{Mõisted ja määratlused}
+\mn{heading=terms and definitions}
+----
+|[source,asciidoc]
+----
+[heading=terms and definitions]
+== Mõisted ja määratlused
+----
+|===
+
+
+
+
+== Foreword
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_foreword.rb[test_foreword.rb].
+
+Another special section is the foreword, which has the canonical name `Foreword` and should be used at the very beginning:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{Foreword}
+First paragraph of foreword.
+
+Second paragraph of foreword.
+----
+|[source,asciidoc]
+----
+[[Foreword]]
+.Foreword
+First paragraph of foreword.
+
+Second paragraph of foreword.
+----
+|===
+
+Just like the other standard sections, you can also pass the canonical name as an attribute:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{Prefazione}
+\mn{heading=foreword}
+Primo paragrafo della prefazione.
+
+Secondo paragrafo della prefazione.
+----
+|[source,asciidoc]
+----
+[[Foreword]]
+.Prefazione
+Primo paragrafo della prefazione.
+
+Secondo paragrafo della prefazione.
+----
+|===
+
+
+
+
+== Blank headings
+
+To define a subclause which is numbered but bears no header text, you can use a blank name:
+
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\subsection{}
+
+This subclause bears no title text.
+----
+|[source,asciidoc]
+----
+=== {blank}
+
+This subclause bears no title text.
+----
+|===
+
+
+
+
+== Deep levels
+
+Metanorma allows headings up to seven levels.
+`LaTeX` has only 5 macros, so we account for the two deepest levels by attaching a `*level*` attribute to `\subparagraph`:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\subparagraph{Heading at level 6}
+\mn{level=6}
+
+\subparagraph{Heading at level 7}
+\mn{level=7}
+----
+|[source,asciidoc]
+----
+[level=6]
+====== Heading at level 6
+
+[level=7]
+====== Heading at level 7
+----
+|===
+
+CAUTION: This feature has bad ergonomics and might change before the next major release.
+
+
+
+
+== Appendices
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_appendix.rb[test_appendix.rb].
+
+You can typeset appendices (i.e. annexes) by using the `\appendix` macro as it's customary in LaTeX.
+After you've called it all `\sections` will be treated as appendices.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{Ordinary section}
+
+Lorem ipsum.
+
+\appendix
+
+\section{My first appendix}
+
+Lorem ipsum.
+
+\section{Another appendix}
+
+Lorem ipsum.
+
+----
+|[source,asciidoc]
+----
+== The last ordinary section
+
+Lorem ipsum.
+
+[appendix]
+== My first appendix
+
+Lorem ipsum.
+
+[appendix]
+== Another appendix
+
+Lorem ipsum.
+----
+|===
+
+Just like other sections, you can pass attributes to appendices. E.g. to change the `obligation`:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\appendix
+\section{My appendix}
+\mn[obligation=informative]
+
+Lorem ipsum.
+----
+|[source,asciidoc]
+----
+[appendix,obligation=informative]
+== My appendix
+
+Lorem ipsum.
+----
+|===
+
+
+
+
+=== Inline headings
+
+You can typeset inline headings by passing `\%inline-header` as an attribute:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\subsection{Inline header,}
+\mn{\%inline-header}
+
+which begins this line.
+----
+|[source,asciidoc]
+----
+[%inline-header]
+=== Inline header,
+
+which begins this line.
+----
+|===
+
+CAUTION: This feature has bad ergonomics and might change before the next major release.
+
+
+
+
+== Language and script
+
+You can set the `language` and the `script` of a section using attributes:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{French section}
+\mn{language=fr}
+
+\section{Math section}
+\mn{script=Zmth}
+----
+|[source,asciidoc]
+----
+[language=fr]
+== French section
+
+[script=Zmth]
+== Math section
+----
+|===
+
+
+
+
+== Obligations
+
+You can set the `obligation` of a section (which can be either `informative` or `normative`) using an attribute:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{Informative section}
+\mn{obligation=informative}
+----
+|[source,asciidoc]
+----
+[obligation=informative]
+== Informative section
+----
+|===
+
+Note that most sections have a fixed default.
+Annexes and clauses default to `normative` but you can set them to `informative`.
+
+
+
+
+:leveloffset: +1
+
+= Symbols and abbreviations
+
+`Symbols and Abbreviations` sections are expected to be simple <<_description_lists,description lists>>.
+
+Metanorma takes care of sorting the symbol entries in the order prescribed by ISO/IEC DIR 2, but it does not support sorting LaTeX math entries.
+Also note that the PDF rendered directly by LaTeX will not be sorted.
+
+:leveloffset!:
+:leveloffset: +1
+
+= Terms and definitions
+
+`Terms and Definitions` subsections must be composed by these elements, in order:
+
+1. a heading of the appropriate level containing the term
+2. an optional `\label` to cross-reference the term from the others
+3. these optional macros, _whose parameter can contain markup_:
+ `\alt`:: to specify alternative/admitted terms
+ `\deprecated`:: to specify deprecated terms
+ `\domain`:: to specify the term domain
+4. the term definition as a normal paragraph
+5. optional examples using the `*example*` environment
+6. optional notes using the `*note*` environment
+7. an optional citation using the `*source*` environment composed by a bibliographic reference followed by optional modification details
+
+Here is a full example:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{Terms and Definitions}
+
+\subsection{paddy}
+\label{paddy}
+\alt{paddy rice}
+\alt{rough \textbf{rice}}
+\deprecated{cargo rice}
+\domain{rice}
+
+rice retaining its husk after threshing
+
+\begin{example}
+ Foreign seeds, husks, bran, sand, dust.
+\end{example}
+
+\begin{note}
+ The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking.
+\end{note}
+
+\begin{source}
+ \mncite[section 3.2]{ISO7301}, The term "cargo rice" is shown as deprecated, and Note 1 to entry is not included here
+\end{source}
+----
+|[source,asciidoc]
+----
+== Terms and Definitions
+
+[[paddy]]
+=== paddy
+alt:[paddy rice]
+alt:[rough **rice**]
+deprecated:[cargo rice]
+domain:[rice]
+
+rice retaining its husk after threshing
+
+[example]
+Foreign seeds, husks, bran, sand, dust.
+
+NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking.
+
+[.source]
+<<ISO7301,section 3.2>>, The term "cargo rice" is shown as deprecated,
+and Note 1 to entry is not included here
+----
+|===
+
+To treat a subsection of `Terms and Definitions` as a normal subsection instead of a term, e.g. an introductory section, you apply the `*.nonterm*` attribute to it as follows:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\section{Terms and definitions}
+
+\subsection{Introduction}
+\mn{.nonterm}
+
+The following terms have non-normative effect, and should be ignored by the ametrical.
+----
+|[source,asciidoc]
+----
+== Terms and definitions
+
+[.nonterm]
+=== Introduction
+The following terms have non-normative effect, and should be ignored by the ametrical.
+----
+|===
+
+:leveloffset!:
+
+:leveloffset!:
+
+:leveloffset: +1
+
+= Text formatting
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_text_formatting.rb[test_text_formatting.rb].
+
+You can set bold, italic, monospace and small caps text using respectively `\textbf`, `\textit`, `\texttt` and `\textsc`.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\textbf{Bold} text.
+
+\textit{Italic} text.
+
+\texttt{Monospace} text.
+
+\textsc{Small caps} text.
+----
+|[source,asciidoc]
+----
+**Bold** text.
+
+__Italic__ text.
+
+``Monospace`` text.
+
+[smallcap]#Small caps# text.
+----
+|===
+
+The _switch_ versions of these macros are available too: `\bfseries`, `\itshape`, `\ttfamily` and `\scshape`.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+{\bfseries Bold} text.
+
+{\itshape Italic} text.
+
+{\ttfamily Monospace} text.
+
+{\scshape Small caps} text.
+----
+|[source,asciidoc]
+----
+**Bold** text.
+
+__Italic__ text.
+
+``Monospace`` text.
+
+[smallcap]#Small caps# text.
+----
+|===
+
+You can set strikethrough, superscript and subscript text using respectively `*\textst*`, `\textsuperscript` and `\textsubscript`.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+Strikethrough \textst{text}.
+
+Superscript \textsuperscript{text}.
+
+Subscript \textsubscript{text}.
+----
+|[source,asciidoc]
+----
+Strikethrough [strike]#text#.
+
+Superscript ^text^.
+
+Subscript ~text~.
+----
+|===
+
+NOTE: Strikethrough text is implemented using the {ctan-pkg-url}/ulem[ulem] package.
+
+:leveloffset!:
+:leveloffset: +1
+
+= Paragraph alignment
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_paragraph_alignment.rb[test_paragraph_alignment.rb].
+
+You can set paragraph alignment explicitly using the `flushleft`, `center` and `flushright` environments.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\begin{flushleft}
+ This paragraph is left aligned.
+\end{flushleft}
+----
+|[source,asciidoc]
+----
+[align=left]
+This paragraph is left aligned.
+----
+|===
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\begin{center}
+ This paragraph is centered.
+\end{center}
+----
+|[source,asciidoc]
+----
+[align=center]
+This paragraph is centered.
+----
+|===
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\begin{flushright}
+ This paragraph is right aligned.
+\end{flushright}
+----
+|[source,asciidoc]
+----
+[align=right]
+This paragraph is right aligned.
+----
+|===
+
+The default alignment is _justified_, so no environment is provided for that.
+
+:leveloffset!:
+:leveloffset: +1
+
+= Cross-references (aka internal references)
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_cross_references.rb[test_cross_references.rb].
+====
+
+To reference some part of the document you must first of all label it using `\label`.
+Many parts of the document accept labels (headings, tables, list items, etc.) and you will find an example in the related section when that's the case.
+
+For the sake of the next examples, let's assume a section labeled `sec:foo` exists.
+
+You can reference `sec:foo` by using the `\ref` macro:
+
+[cols="a,a"]
+|===
+|[source,latex]
+Go look at \ref{sec:foo}.
+|[source,asciidoc]
+Go look at <<sec:foo>>.
+|===
+
+To reference `sec:foo` with a custom text you can use the `\hyperref` macro:
+
+[cols="a,a"]
+|===
+|[source,latex]
+Go look at \hyperref[sec:foo]{this}.
+|[source,asciidoc]
+Go look at <<sec:foo, this>>.
+|===
+
+:leveloffset!:
+:leveloffset: +1
+
+= Links (aka external references)
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_links.rb[test_links.rb].
+====
+
+References can also point to URLs identifying resources external to the document.
+
+You can link to a website by using the `\url` macro:
+
+[cols="a,a"]
+|===
+|[source,latex]
+Go look at \url{https://www.metanorma.com/}.
+|[source,asciidoc]
+Go look at link:++https://www.metanorma.com/++[].
+|===
+
+To link to a website with a custom text you can use the `\href` macro:
+
+[cols="a,a"]
+|===
+|[source,latex]
+Go look at \href{https://www.metanorma.com/}{Metanorma home}.
+|[source,asciidoc]
+Go look at link:++https://www.metanorma.com/++[Metanorma home].
+|===
+
+:leveloffset!:
+
+== Bibliography and citations
+:leveloffset: +2
+
+= Bibliography
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_bibliography.rb[test_bibliography.rb].
+
+You can cite a bibliographic source using the `\cite` macro as usual.
+
+CAUTION: Multiple citations, e.g. `\cite{KEY1,KEY2}` are not supported.
+
+The bibliographic database can be specified in two different ways.
+
+If the bibliography is small or you want to typeset each entry manually you can use the `thebibliography` environment to wrap a list of bibliographic items described by `\bibitem`.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+
+\begin{document}
+
+ This document cites \cite{ISO7301}.
+ It also cites \cite{einstein}.
+
+ \begin{thebibliography}{2}
+ \bibitem[ISO 7301]{ISO7301}
+ Rice -- Specification
+
+ \bibitem{einstein}
+ Albert Einstein.
+ \textit{Zur Elektrodynamik bewegter K{\"o}rper}. (German)
+ [\textit{On the electrodynamics of moving bodies}].
+ Annalen der Physik, 322(10):891–921, 1905.
+ \end{thebibliography}
+\end{document}
+----
+|
+[source,asciidoc]
+----
+This document cites <<ISO7301>>.
+It also cites <<einstein>>.
+
+[bibliography]
+== References
+
+* [[[ISO7301,ISO 7301]]]
+Rice – Specification
+
+* [[[einstein,2]]]
+Albert Einstein.
+__Zur Elektrodynamik bewegter Körper__. (German)
+[__On the electrodynamics of moving bodies__].
+Annalen der Physik, 322(10):891–921, 1905.
+----
+|===
+
+If the bibliography is big or you have an existing BibTeX database, you can use that too by passing the filename to the `\bibliography` macro.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\documentclass{metanorma}
+
+\begin{document}
+ Everyone should read \cite{einstein}.
+ Many interesting books are found in \cite{knuthwebsite}.
+
+ \bibliography{my_database.bib}
+\end{document}
+----
+.Contents of `my_database.bib`
+[source,bibtex]
+----
+@article{einstein,
+ author = "Albert Einstein",
+ title = "{Zur Elektrodynamik bewegter K{\"o}rper}. ({German})
+ [{On} lectrodynamics of moving bodies]",
+ journal = "Annalen der Physik",
+ volume = "322",
+ number = "10",
+ pages = "891--921",
+ year = "1905",
+ DOI = "http://dx.doi.org/10.1002/andp.19053221004"
+}
+
+@misc{knuthwebsite,
+ author = "Donald Knuth",
+ title = "Knuth: Computers and Typesetting",
+ url = "http://www-cs-faculty.stanford.edu/\~{}uno/abcde.html"
+}
+----
+|
+[source,asciidoc]
+----
+Everyone should read <<einstein>>.
+Many interesting books are found in <<knuthwebsite>>.
+
+[bibliography]
+== References
+
+* [[[einstein,1]]]
+{blank}A. Einstein (1905)
+Zur Elektrodynamik bewegter Körper. (German) [On the electrodynamics of moving bodies].
+Annalen der Physik322 (10), pp. 891–921.
+External Links: http://dx.doi.org/10.1002/andp.19053221004[Document]
+
+* [[[knuthwebsite,3]]]
+{blank}D. Knuth
+Knuth: computers and typesetting.
+External Links: http://www-cs-faculty.stanford.edu/\~uno/abcde.html[Link]
+----
+|===
+
+CAUTION: While you can use bibliographic styles on the `LaTeX` side and
+https://www.relaton.com/[Relaton] databases on the `Adoc` side,
+these features are still not supported on the opposing side.
+
+:leveloffset!:
+:leveloffset: +2
+
+= Advanced citations
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_mncite.rb[test_mncite.rb].
+
+To leverage the full power of Metanorma you can use `*\mncite*` to typeset bibliographic references.
+
+`*\mncite*` accepts three arguments as `\mncite[<1>]{<2>}[<3>]`:
+
+1. the first argument (optional) is the citation which will be rendered literally;
+2. the second argument (mandatory) is the bibliographic key;
+3. the third argument (optional) is a list of https://www.metanorma.com/author/topics/document-format/bibliography/#localities[localities].
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\mncite{ISO712}
+
+\mncite[the foregoing reference]{ISO712}
+
+\mncite{ISO712}[section=5,page=8-10]
+
+\mncite[5:8-10]{ISO712}[section=5,page=8-10]
+----
+|
+[source,asciidoc]
+----
+<<ISO712>>
+
+<<ISO712,the foregoing reference>>
+
+<<ISO712,section=5,page=8-10>>
+
+<<ISO712,section=5,page=8-10,5:8-10>>
+----
+|===
+
+
+CAUTION: Multiple citations, e.g. `\cite{KEY1,KEY2}` are not supported.
+
+CAUTION: Localities are not rendered by the LaTeX class yet, only by Metanorma compilation.
+
+:leveloffset!:
+
+:leveloffset: +1
+
+= Block quotations
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_block_quotations.rb[test_block_quotations.rb].
+
+You can typeset block quotations using the `quote` environment:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\begin{quote}
+ This is a block quotation.
+\end{quote}
+----
+|
+[source,asciidoc]
+----
+ [quote]
+ ____
+ This is a block quotation.
+ ____
+----
+|===
+
+The attribution and the citation title can be passed through to AsciiDoc by using the `*\mn*` macro:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\begin{quote}
+ \mn{ISO,"ISO7301, section 1"}
+ This is a block quotation.
+\end{quote}
+----
+|
+[source,asciidoc]
+----
+ [quote,ISO,"ISO7301, section 1"]
+ ____
+ This is a block quotation.
+ ____
+----
+|===
+
+CAUTION: This feature is not complete; attribution and citation title are currently not rendered by `LaTeX`.
+
+:leveloffset!:
+:leveloffset: +1
+
+= Lists
+
+All usual typologies of lists available in `LaTeX` can be used;
+as usual, they work by listing items usinf the `\item` macro inside a specific environment.
+
+== Ordered lists
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_ordered_lists.rb[test_ordered_lists.rb].
+
+You can typeset ordered lists using the `enumerate` environment:
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{enumerate}
+ \item Hey,
+ \item ho,
+ \item let's go!
+\end{enumerate}
+|[source,asciidoc]
+. Hey,
+. ho,
+. let’s go!
+|===
+
+== Unordered lists
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_unordered_lists.rb[test_unordered_lists.rb].
+
+You can typeset unordered lists using the `itemize` environment:
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{itemize}
+ \item Foo
+ \item Bar
+ \item Baz
+\end{itemize}
+|[source,asciidoc]
+* Foo
+* Bar
+* Baz
+|===
+
+== Description lists
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_description_lists.rb[test_description_lists.rb].
+
+You can typeset description lists using the `description` environment:
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{description}
+ \item[Lee] bass guitar and lead vocals
+ \item[Lifeson] guitars and backing vocals
+ \item[Peart] drums and percussion
+\end{description}
+|[source,asciidoc]
+Lee:: bass guitar and lead vocals
+Lifeson:: guitars and backing vocals
+Peart:: drums and percussion
+|===
+
+
+
+
+== Nested lists
+
+NOTE: These features are verified by tests in {repo-blob-url}/test/test_stressed_lists.rb[test_stressed_lists.rb].
+
+You can nest ordered, unordered and description lists freely.
+
+CAUTION: While `AsciiDoc` has no depth limit, `LaTeX` is limited to a depth of 4.
+
+
+
+
+// TODO: == Long items and paragraph breaks
+
+:leveloffset!:
+:leveloffset: +1
+
+= Math
+
+[NOTE]
+====
+These features are verified by tests in
+{repo-blob-url}/test/test_math_inline.rb[test_math_inline.rb] and
+{repo-blob-url}/test/test_math_display.rb[test_math_display.rb].
+====
+
+You can typeset inline math delimiting it with `S`/`$` pairs:
+
+[cols="a,a"]
+|===
+|[source,latex]
+Euler's identity is $e^{i\pi}+1=0$.
+|[source,asciidoc]
+Euler's identity is stem:[e^{i\pi}+1=0].
+|===
+
+You can typeset display math delimiting it with `\[`/`\]` pairs:
+
+[cols="a,a"]
+|===
+|[source,latex]
+Here is the Binomial Theorem:
+\[(1+x)^n = \sum_{k=0}^n {n \choose k}x^k\]
+|[source,asciidoc]
+----
+Here is the Binomial Theorem:
+
+[stem]
+++++
+(1+x)^n = \sum_{k=0}^n {n \choose k}x^k
+++++
+----
+|===
+
+// TODO: Whould we make it explicit about `:stem: latexmath`?
+// TODO: == Math environments
+// TODO: == Formulae, see https://www.metanorma.com/author/topics/document-format/text/#formulae
+
+:leveloffset!:
+:leveloffset: +1
+
+= Tables
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_tables.rb[test_tables.rb].
+====
+
+You can typeset simple tables using the `tabular` environment:
+
+[cols="a,a",separator=!]
+!===
+![source,latex]
+\begin{tabular}{ll}
+ A & B \\
+ C & D \\
+\end{tabular}
+![source,asciidoc]
+----
+[cols=2*]
+|===
+| A
+| B
+
+| C
+| D
+|===
+----
+!===
+
+You can add labels and captions by wrapping a `tabular` with the `table` environment and using the `\label` and `\caption` macros:
+
+[cols="a,a",separator=!]
+!===
+![source,latex]
+\begin{table}
+ \label{tab:example}
+ \caption{This is the caption}
+ \begin{tabular}{ll}
+ A & B \\
+ C & D \\
+ \end{tabular}
+\end{table}
+![source,asciidoc]
+----
+[[tab:example]]
+.This is the caption
+[cols=2*]
+|===
+| A
+| B
+
+| C
+| D
+|===
+----
+!===
+
+:leveloffset!:
+:leveloffset: +1
+
+= Figures
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_figures.rb[test_figures.rb].
+====
+
+You can typeset figures by using the `figure` environment.
+
+Use `\includegraphics` to include an image.
+
+Use `\label` and `\caption` to add labels and captions to figures.
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{figure}
+ \label{fig:example}
+ \caption{This is the caption}
+ \includegraphics{example.jpg}
+\end{figure}
+|[source,asciidoc]
+----
+[[fig:example]]
+.This is the caption
+image::example.jpg[]
+----
+|===
+
+
+
+
+== Subfigures
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_subfigures.rb[test_subfigures.rb].
+====
+
+To typeset a figure containing subfigures you can nest the `subfigure` environment inside a `figure`.
+
+The macros `\caption` and `\label` work as you would expect inside subfigures too.
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{figure}\centering
+ \begin{subfigure}[b]{0.4\textwidth}
+ \includegraphics[width=\textwidth]{left.jpg}
+ \caption{A subfigure on the left}
+ \label{fig:left}
+ \end{subfigure}
+ \qquad
+ \begin{subfigure}[b]{0.4\textwidth}
+ \includegraphics[width=\textwidth]{right.jpg}
+ \caption{A subfigure on the right}
+ \label{fig:right}
+ \end{subfigure}
+ \caption{A figure with two subfigures}
+ \label{fig:whole}
+\end{figure}
+|[source,asciidoc]
+----
+[[fig:whole]]
+.A figure with two subfigures
+====
+[[fig:left]]
+.A subfigure on the left
+image::left.jpg[]
+
+[[fig:right]]
+.A subfigure on the right
+image::right.jpg[]
+
+====
+----
+|===
+
+NOTE: Subfigures are implemented using the {ctan-pkg-url}/subcaption[subcaption] package.
+
+
+
+
+== Keys
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_figures_key.rb[test_figures_key.rb].
+====
+
+
+To typeset the key for a figure you can use a `*key*` environment (which behaves like a `description`) inside a `\paragraph` titled `Key`.
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{figure}
+ \includegraphics{example.jpg}
+ \label{fig:example}
+ \caption{This is the caption}
+ \paragraph*{Key}
+ \begin{key}
+ \item[A] First letter
+ \item[B] Second letter
+ \item[C] Third letter
+ \end{key}
+\end{figure}
+|[source,asciidoc]
+----
+[[fig:example]]
+.This is the caption
+image::example.jpg[]
+
+*Key*
+
+A::
+First letter
+B::
+Second letter
+C::
+Third letter
+----
+|===
+
+NOTE: Figures keys are implemented using the {ctan-pkg-url}/enumitem[enumitem] package.
+
+:leveloffset!:
+:leveloffset: +1
+
+= Footnotes
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_footnotes.rb[test_footnotes.rb].
+====
+
+You can typeset footnotes by using `\footnote`:
+
+[cols="a,a"]
+|===
+|[source,latex]
+Footnotes are useful\footnote{Unless abused.}.
+|[source,asciidoc]
+Footnotes are useful footnote:[Unless abused.].
+|===
+
+// TODO: === Footnotes in tables
+// TODO: === Footnotes in figures
+
+:leveloffset!:
+:leveloffset: +1
+
+= Requirements, Recommendations, and Permissions
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_blocks.rb[test_blocks.rb].
+====
+
+You can typeset requirements, recommendations, and permissions by using the homonymous environments `*requirement*`, `*recommendation*` and `*permission*`:
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{requirement}
+ This is a requirement block.
+\end{requirement}
+|[source,asciidoc]
+----
+[.requirement]
+====
+This is a requirement block.
+====
+----
+|===
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{recommendation}
+ This is a recommendation block.
+\end{recommendation}
+|[source,asciidoc]
+----
+[.recommendation]
+====
+This is a recommendation block.
+====
+----
+|===
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{permission}
+ This is a permission block.
+\end{permission}
+|[source,asciidoc]
+----
+[.permission]
+====
+This is a permission block.
+====
+----
+|===
+
+== Attributes
+
+CAUTION: TODO
+
+== Nesting
+
+Requirements, recommendations and permissions can be nested:
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\begin{requirement}
+ Here is a nested requirement.
+
+ \begin{requirement}
+ First nested requirement.
+ \end{requirement}
+
+ Here is another nested requirement.
+
+ \begin{requirement}
+ Second nested requirement.
+ \end{requirement}
+\end{requirement}
+----
+|[source,asciidoc]
+----
+[.requirement]
+====
+Here is a nested requirement.
+
+[.requirement]
+=====
+First nested requirement.
+=====
+
+Here is another nested requirement.
+
+[.requirement]
+======
+Second nested requirement.
+======
+====
+----
+|===
+
+== Internal structure
+
+The internal structure of requirements, recommendations and permissions can be further marked up with environments which will help making the document machine-readable. Such environments are: `*specification*`, `*measurement-target*`, `*verification*`, and `*import*`.
+
+[cols="a,a"]
+|===
+|[source,latex]
+----
+\begin{requirement}
+ This is descriptive text.
+
+ \begin{specification}
+ This is a formal statement, which may be considered the object of the requirement.
+ \end{specification}
+
+ \begin{measurement-target}
+ This is a quantitative measure for the requirement.
+ \end{measurement-target}
+
+ \begin{verification}
+ This is a verification step for the requirement
+ \end{verification}
+
+ \begin{import}
+ This is a code stub.
+ \end{import}
+\end{requirement}
+----
+|[source,asciidoc]
+----
+[.requirement]
+====
+This is descriptive text.
+
+[.specification]
+--
+This is a formal statement, which may be considered the object of the requirement.
+--
+
+[.measurement-target]
+--
+This is a quantitative measure for the requirement.
+--
+
+[.verification]
+--
+This is a verification step for the requirement
+--
+
+[.import]
+--
+This is a code stub.
+--
+====
+----
+|===
+
+:leveloffset!:
+:leveloffset: +1
+
+= Reviewer notes
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_reviewer_notes.rb[test_reviewer_notes.rb].
+====
+
+You can typeset reviewer notes by using the `*reviewernotes*` environment.
+
+By using `*\mn*` at the beginning of the environment you can set the following attributes:
+
+`reviewer` (_mandatory_)::
+Name of the reviewer
+`from` (_mandatory_)::
+Starting target anchor
+`to` (_optional_)::
+Ending target anchor
+`date` (_optional_)::
+Date attribute (optionally including time)
+
+Here is a full example:
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{reviewernote}
+ \mn{reviewer="John Doe",date=20180125T0121,from=A,to=B}
+ Lorem ipsum.
+\end{reviewernote}
+|[source,asciidoc]
+----
+[reviewer="John Doe",date=20180125T0121,from=A,to=B]
+****
+Lorem ipsum.
+****
+----
+|===
+
+CAUTION: The `reviewer` and `date` attributes are currently not rendered by LaTeX but only passed to Adoc.
+
+:leveloffset!:
+:leveloffset: +1
+
+= Todos
+
+[NOTE]
+====
+These features are verified by tests in {repo-blob-url}/test/test_todos.rb[test_todos.rb].
+====
+
+You can typeset todo notes by using the `*todo*` environment.
+
+By using `*\mn*` at the beginning of the environment you can set the following attributes:
+
+`reviewer` (_optional_)::
+Name of the reviewer
+`from` (_optional_)::
+Starting target anchor
+`to` (_optional_)::
+Ending target anchor
+`date` (_optional_)::
+Date attribute (optionally including time)
+
+Here is a full example:
+
+[cols="a,a"]
+|===
+|[source,latex]
+\begin{todo}
+ \mn{reviewer="John Doe",date=20180125T0121,from=A,to=B}
+ Lorem ipsum.
+\end{todo}
+|[source,asciidoc]
+----
+[TODO,reviewer="John Doe",date=20180125T0121,from=A,to=B]
+====
+Lorem ipsum.
+====
+----
+|===
+
+CAUTION: The `reviewer` and `date` attributes are currently not rendered by LaTeX but only passed to Adoc.
+
+:leveloffset!: \ No newline at end of file