From f2e574335d36a1b6199257528ad1d66d442fe05c Mon Sep 17 00:00:00 2001 From: Ronald Tse Date: Wed, 6 Mar 2024 18:57:49 +0800 Subject: [PATCH] chore: content fixes --- .lycheeignore | 3 +- _pages/developer.adoc | 2 +- _pages/learn.adoc | 10 ++-- _sass/metanorma-rules.scss | 33 +++++++++--- .../authoring-guide/terms-definitions.adoc | 2 +- .../ogc/authoring-guide/cross-references.adoc | 51 ------------------- learn/lessons/exercises.adoc | 50 +++++++++--------- learn/lessons/lesson-1-1.adoc | 18 ++++--- learn/lessons/lesson-1-2.adoc | 16 +++--- learn/lessons/lesson-1-3.adoc | 8 +-- learn/lessons/lesson-1.adoc | 6 ++- learn/lessons/lesson-2-1.adoc | 18 ++++--- learn/lessons/lesson-2-2.adoc | 18 ++++--- learn/lessons/lesson-2-3-1.adoc | 12 +++-- learn/lessons/lesson-2-3-2.adoc | 14 ++--- learn/lessons/lesson-2-3-3.adoc | 12 +++-- learn/lessons/lesson-2-3-4.adoc | 8 +-- learn/lessons/lesson-2-3-5.adoc | 12 +++-- learn/lessons/lesson-2-3-6.adoc | 8 +-- learn/lessons/lesson-2-3.adoc | 6 +-- learn/lessons/lesson-2-4-1.adoc | 18 ++++--- learn/lessons/lesson-2-4-2.adoc | 4 +- learn/lessons/lesson-2-4-3.adoc | 30 ++++++----- learn/lessons/lesson-2-4.adoc | 4 +- learn/lessons/lesson-2-5.adoc | 10 ++-- learn/lessons/lesson-2.adoc | 16 +++--- learn/lessons/lesson-3-1.adoc | 8 +-- learn/lessons/lesson-3-2.adoc | 6 ++- learn/lessons/lesson-3.adoc | 10 ++-- learn/lessons/lesson-4-1.adoc | 14 ++--- learn/lessons/lesson-4-2.adoc | 44 ++++++++-------- learn/lessons/lesson-4-3.adoc | 15 +++--- learn/lessons/lesson-4.adoc | 8 +-- nav-links.html | 12 ++--- .../standoc_document_attributes.yaml | 4 +- 35 files changed, 265 insertions(+), 245 deletions(-) diff --git a/.lycheeignore b/.lycheeignore index 0f9bd00c..731be4fd 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -9,4 +9,5 @@ ldap://.* http://www.idpf.org/2007/ops # These links are due to redirect_from and cannot be fixed https://www.metanorma.org/developer/ -https://www.metanorma.org/installation/ \ No newline at end of file +https://www.metanorma.org/installation/ +https://www.metanorma.org/install/ \ No newline at end of file diff --git a/_pages/developer.adoc b/_pages/developer.adoc index f8e76cf9..f5c6fc16 100644 --- a/_pages/developer.adoc +++ b/_pages/developer.adoc @@ -6,7 +6,7 @@ redirect_from: - /developer/ --- -= Developer documentation +== Developer documentation To build documents with Metanorma, you need to have the Metanorma command-line toolchain installed. diff --git a/_pages/learn.adoc b/_pages/learn.adoc index c7f247b4..ae53e128 100644 --- a/_pages/learn.adoc +++ b/_pages/learn.adoc @@ -21,13 +21,13 @@ You will learn about: == Prerequisites -* https://www.metanorma.org/install/[Install Metanorma] +* link:/install/[Install Metanorma] + -TIP: Use Metanorma in Docker to get started faster. +TIP: Use Metanorma in Docker to get started faster. +* Download the https://github.com/metanorma/metanorma-tutorial[Metanorma tutorial project]. -* Download the https://github.com/metanorma/metanorma-tutorial[Metanorma tutorial project]. - -link:/learn/lessons/lesson-1/">Start tutorial » ++++ +
Start tutorial »
+++ == After the course diff --git a/_sass/metanorma-rules.scss b/_sass/metanorma-rules.scss index 3563b1c2..3584133b 100644 --- a/_sass/metanorma-rules.scss +++ b/_sass/metanorma-rules.scss @@ -68,12 +68,6 @@ body.overview section.documentation { } } -.cta .button .tutorial { - @include cta-button($primary-dark-color, #ffffff); - border-radius: 25px; - &:hover {background-color: #9c60c1ff}; -} - .web-build-ui { &.conditional { @@ -296,3 +290,30 @@ body > .underlay > header { @include docs-page($primary-dark-color); } } + +/* Learn layout style */ +body.layout--learn { + article > header > nav.subitems { + display: none; + } + + .ulist.checklist > ul.checklist { + list-style: none; + } + + .cta.tutorial { + .button { + @include cta-button($primary-dark-color, #ffffff); + border-radius: 25px; + &:hover {background-color: #9c60c1ff}; + } + } + + + details { + summary.title { + background-color: #28388A !important; + &:hover {background-color: #9c60c1ff !important}; + } + } +} diff --git a/author/ieee/authoring-guide/terms-definitions.adoc b/author/ieee/authoring-guide/terms-definitions.adoc index a5dfdb73..c4564fdb 100644 --- a/author/ieee/authoring-guide/terms-definitions.adoc +++ b/author/ieee/authoring-guide/terms-definitions.adoc @@ -3,7 +3,7 @@ layout: ieee-flavor title: Terms and definitions --- //// -This text is copied and pasted from metanorma.org:staging /tutorials/tutorial_complete.adoc +This text is copied and pasted from metanorma.org:staging /learn/tutorial_complete.adoc Once staging is merged into main --> Reuse //// diff --git a/author/ogc/authoring-guide/cross-references.adoc b/author/ogc/authoring-guide/cross-references.adoc index f5464d99..b4f42f78 100644 --- a/author/ogc/authoring-guide/cross-references.adoc +++ b/author/ogc/authoring-guide/cross-references.adoc @@ -103,54 +103,3 @@ To reference an *external* source: ---- http://www.iso.org/[International Organization for Standardization]. ---- - -== Internal references - -To link to an important section, table, figure, formula, or list item in your document: - -. Set an anchor using double square brackets before the content you want to reference: `\[[anchor]]`. -+ -.Example for an anchor preceding an image -[source,adoc] ----- -[[figureC-1]] -.Typical gelatinization curve -image::images/rice_image2.png[Image of the gelatinization curve] ----- -+ -.Rendered image caption -image::/assets/author/learn/references_img_anchor.jpg[] - -. To reference an anchor, type the anchor name like this `\<>`. -+ -[source,adoc] ----- -<> gives an example of a typical gelatinization curve. ----- -+ -.Rendered reference -image::/assets/author/learn/references_img_target.jpg[] - -. To set an alternative text other than the anchor text, append the text inside the brackets using a comma. -+ -[source,adoc] ----- -<> gives an example of a typical gelatinization curve. ----- - -=== Auto-numbering of references - -Metanorma automatically numbers and names references; because they are -auto-numbered, they will be renumbered automatically if you insert any new text -of the same type. - -Metanorma markup is serialized into XML, hence the anchor should follow the https://www.w3.org/TR/xml-names11/[XML namespace conventions]. - -i.e., an anchor name name must not contain: - -* colons -* whitespaces -* words starting with numbers - -If you want to learn more about the technical aspects of cross-references, read -link:/author/concepts/deep-dive-cross-references[Deep-dive into cross-references]. diff --git a/learn/lessons/exercises.adoc b/learn/lessons/exercises.adoc index 639e78cc..a49e2f12 100644 --- a/learn/lessons/exercises.adoc +++ b/learn/lessons/exercises.adoc @@ -4,13 +4,13 @@ https://shopify.github.io/liquid/tags/control-flow/ //// :page-liquid: -The code for this exercise is available on https://github.com/metanorma/metanorma-learn/tree/master/sources/standard[GitHub]. +The code for this exercise is available on https://github.com/metanorma/metanorma-tutorial/tree/master/sources/standard[GitHub]. The corresponding file is named `{{include.content}}.adoc` {% case {{include.content}} %} {% when "exercise-2-1" %} -Now it’s your turn. Fill the document with the following attributes: +Now it’s your turn. Fill the document with the following attributes: [%interactive] * [ ] Document title @@ -25,14 +25,14 @@ Now it’s your turn. Fill the document with the following attributes: .Hint [%collapsible] ==== -To declare an attribute, follow the syntax `:attribute: value`. +To declare an attribute, follow the syntax `:attribute: value`. For example: `:publisher: Ribose Inc.` -==== +==== {% when "exercise-2-2" %} -Look at the prepopulated Metanorma document. -There are many clauses describing the content but there are sections missing to form a correct standard document. +Look at the prepopulated Metanorma document. +There are many clauses describing the content but there are sections missing to form a correct standard document. Add the following sections: [%interactive] @@ -57,9 +57,9 @@ Add lists to the prepopulated document. ==== Ordered list items start with a dot, followed by a blank: `. List item`. -Unordered list items start with an asterisk, followed by a blank: `* List item`. +Unordered list items start with an asterisk, followed by a blank: `* List item`. -To write a definition list, follow the syntax: +To write a definition list, follow the syntax: `term:: Definition` ==== @@ -119,7 +119,7 @@ The structure for a three column table looks like this: {% when "exercise-2-3-4" %} Insert a diagram of of a rice plant in line 17 by following the steps below: [%interactive] -* [ ] Add an image macro. +* [ ] Add an image macro. * [ ] Populate the `image::` macro with this link: + ---- https://en.wikipedia.org/wiki/Open_Geospatial_Consortium#/media/File:GeoServer_GeoNetwork_with_web_app.svg @@ -136,7 +136,7 @@ Data stores:: Contain databases and shape files. .Hint [%collapsible] ==== -The syntax for images is: `image::URL[]`. +The syntax for images is: `image::URL[]`. Make sure to include the square brackets after the link. ==== @@ -156,7 +156,7 @@ To create admonitions that span several lines, you need to declare a block. ---- [NOTE] ==== -This is a long note. +This is a long note. It contains three lines. Line three. ==== @@ -164,7 +164,7 @@ Line three. ====== {% when "exercise-2-3-6" %} -There are some code samples in the document but they are not neatly packed into `source` blocks, so they cause trouble. +There are some code samples in the document but they are not neatly packed into `source` blocks, so they cause trouble. [%interactive] * [ ] Create a source block with the attribute `ruby` for the code in lines 20-35. @@ -195,7 +195,7 @@ Format the text using the following formatting: * [ ] Add a footnote on line 30 to explain the OGC Innovation Program. Footnote text: See all active initatives at the OGC wesite. https://www.ogc.org/projects/initiatives/active. {% when "exercise-2-4-2" %} -Let's add some index entries to the text. +Let's add some index entries to the text. [%interactive] * [ ] Add a visible index entry to "OGC" on line 25 * [ ] Add an invisible three level index entry after "FAIR" on line 27: FAIR, findability, accessibility @@ -213,13 +213,13 @@ Hidden index terms: `(\((Level 1 index term, Level 2 index term, Level 3 index t {% when "exercise-2-4-3" %} Let's add some references to the sample document. -Internal references: +Internal references: [%interactive] * [ ] Create an anchor for the table called `tab-properties-of-the-descriptiontype-structure` * [ ] Replace the word "ANCHOR" in line 44 with a reference to the table. -Bibliographic references: -The text references some standards which don't have a matching entry in the bibliography section. Add the following bibliographic references: +Bibliographic references: +The text references some standards which don't have a matching entry in the bibliography section. Add the following bibliographic references: [%interactive] * [ ] dcat, W3C vocab-dcat, W3C: *Data Catalog Vocabulary,* W3C Recommendation 16 January 2014, https://www.w3.org/TR/vocab-dcat/ @@ -243,12 +243,12 @@ The text contains some typos. Mark the errors using comments. {% when "exercise-3-2" %} Let's check out what happens when we compile `exercise-3-2.adoc` -To compile our document: +To compile our document: . Open a new terminal . Start Docker using Docker Desktop. -. Go to the directory where your Metanorma document(s) are stored. For example: -+ +. Go to the directory where your Metanorma document(s) are stored. For example: ++ [source,sh] ---- $ cd Documents/Metanorma/metanorma-tutorial @@ -273,15 +273,15 @@ docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma com [%collapsible] ==== . Relaton fetches checks the cited standards if it can fetch some information automatically. -. +. ==== {% when "exercise-4-2" %} -The following document doesn't compile because there are some errors. +The following document doesn't compile because there are some errors. . Enter `metnanorma exercise-4-2.adoc` to trigger the build process. -. Have a look at the error messages. -. Try to debug the document. If you get stuck, have a look at the hints. +. Have a look at the error messages. +. Try to debug the document. If you get stuck, have a look at the hints. . Once you solved the errors, run the compilation command again to see if the document is build. .Hint Error 1 @@ -295,13 +295,13 @@ You can solve this error by renaming one of the anchors. [%collapsible] ==== Line 76: The file that should be included cannot be found. -Since the scope section already contains text, you can delete the reference. +Since the scope section already contains text, you can delete the reference. ==== .Hint Error 3 [%collapsible] ==== -Line 236: The image attribute contains a whitespace after `image::`, so the path is invalid. Delete the whitespace. +Line 236: The image attribute contains a whitespace after `image::`, so the path is invalid. Delete the whitespace. ==== {% else %} Couldn't load exercise. diff --git a/learn/lessons/lesson-1-1.adoc b/learn/lessons/lesson-1-1.adoc index 6d2da30b..ebf711a4 100644 --- a/learn/lessons/lesson-1-1.adoc +++ b/learn/lessons/lesson-1-1.adoc @@ -5,7 +5,7 @@ title: What is Metanorma? == What you get is what you see vs. What you get is what you mean //include::/author/concepts/wysiwyg_vs_wysiwym.adoc[tag=tutorial] -Word is probably your go-to application for casual writing, such as letters, invitations - and with good reason, because Word has many benefits, such as: +Word is probably your go-to application for casual writing, such as letters, invitations - and with good reason, because Word has many benefits, such as: * Creating documents quickly * An intuitive interface @@ -16,9 +16,9 @@ image::/assets/author/concepts/word_WSYIWYG.png[Word is a WYSIWYG application] However, have you ever written a longer text, with many references, like a scientific text? Then you might have experienced some pain with Word: It tends to mess up the formatting, even if you use templates. Reference management in Word is also no fun, but the worst: Word tends to crash for very long documents, like standards. -Because of these issues, another approach to creating documents is popular: “What you see is what you mean” (WYSIWYM). This concept differs from WYSIWYG because you separate the content and the layout into separate files. To tell the compiler how the text should look or behave, you use markup language. You may have heard about Markdown or LaTeX, which are popular markup languages, but Metanorma uses AsciiDoc. +Because of these issues, another approach to creating documents is popular: “What you see is what you mean” (WYSIWYM). This concept differs from WYSIWYG because you separate the content and the layout into separate files. To tell the compiler how the text should look or behave, you use markup language. You may have heard about Markdown or LaTeX, which are popular markup languages, but Metanorma uses AsciiDoc. -The benefit is that you can publish different outputs from one source, for example into PDF or HTML. Since the layout is stored in a separate file, each output can even be styled differently. +The benefit is that you can publish different outputs from one source, for example into PDF or HTML. Since the layout is stored in a separate file, each output can even be styled differently. .Metanorma uses AsciiDoc text as an input and can deliver different outputs, such as PDF and HTML. A stylesheet determines how the outcome looks like. image::/assets/author/concepts/metanorma_WSYIWYM.png[What you see is what you mean] @@ -28,12 +28,12 @@ image::/assets/author/concepts/metanorma_WSYIWYM.png[What you see is what you me Metanorma is actually not one thing, but three: -. The Metanorma toolchain: This is the software that you use to create documents and generate output. -. Document metamodels: Metanorma provides a document structure for standardization documents, specified in https://www.isotc154.org/projects/iso-36001/[ISO 36001]. Since each organization has different requirements for their standard documents, they use a https://www.metanorma.org/flavors/[“flavor”] of Metanorma. A flavor is a document model that provides additional metadata to reflect the SDO’s needs. -. XML schemas: To use the defined document metamodels, there needs to be a machine-readable file so that documents can be checked against their intended structure. +. The Metanorma toolchain: This is the software that you use to create documents and generate output. +. Document metamodels: Metanorma provides a document structure for standardization documents, specified in https://www.isotc154.org/projects/iso-36001/[ISO 36001]. Since each organization has different requirements for their standard documents, they use a https://www.metanorma.org/flavors/[“flavor”] of Metanorma. A flavor is a document model that provides additional metadata to reflect the SDO’s needs. +. XML schemas: To use the defined document metamodels, there needs to be a machine-readable file so that documents can be checked against their intended structure. Metanorma consists of several layers of complexity, see the figure below. -The basis for each metanorma document is AsciiDoc. Since AsciiDoc itself has limited functionalities for authoring standards, Metanorma extends AsciiDoc as one part of the Metanorma toolchain (1). Metanorma AsciiDoc provides advanced features, such as automatically linking the correct standard in a bibliography section. +The basis for each metanorma document is AsciiDoc. Since AsciiDoc itself has limited functionalities for authoring standards, Metanorma extends AsciiDoc as one part of the Metanorma toolchain (1). Metanorma AsciiDoc provides advanced features, such as automatically linking the correct standard in a bibliography section. The final layer of complexity are flavour-specific document rules and best practices based on the document metamodels (2). For example, ISO documents must include a "Scope" section, whereas NIST requires an "Acknowledgements" section. .Metanorma extends AsciiDoc provide a powerful tool for standard organizations @@ -51,4 +51,6 @@ Metanorma has many advantages when you want to edit standards: Let’s explore the workflow of Metanorma in the next lesson. -link:/learn/lessons/lesson-1-2/[Start next lesson »] ++++ +
Start next lesson »
++++ diff --git a/learn/lessons/lesson-1-2.adoc b/learn/lessons/lesson-1-2.adoc index 74b3acb6..686addcc 100644 --- a/learn/lessons/lesson-1-2.adoc +++ b/learn/lessons/lesson-1-2.adoc @@ -13,7 +13,7 @@ The Metanorma workflow consists of six phases: . Publication -.The Metanorma workflow from start to finish +.The Metanorma workflow from start to finish image::/assets/author/concepts/metanorma_workflow.png[The Metanorma workflow] == Document creation @@ -26,11 +26,11 @@ You can create a new standard document either by: *New file* -The easiest way is to create a document from scratch, by creating an empty AsciiDoc file (`.adoc`) in the desired folder. +The easiest way is to create a document from scratch, by creating an empty AsciiDoc file (`.adoc`) in the desired folder. *Templates* -Templates get you started faster, as they provide the structure of a standard document already. If your organization provides templates, you can create a new document based on a template using the command line. +Templates get you started faster, as they provide the structure of a standard document already. If your organization provides templates, you can create a new document based on a template using the command line. *Import from Word* @@ -56,7 +56,7 @@ All errors are logged to the terminal and are saved to an Error file (.`err`). O == Output generation -The Metanorma toolchain compiles documents in the following formats: +The Metanorma toolchain compiles documents in the following formats: * Metanorma XML * HTML @@ -73,7 +73,7 @@ The HTML output is in HTML 5. All HTML output has a sidebar with a Javascript-ge *PDF* -Metanorma generates PDF output from XML. The styling comes from an https://www.xml.com/articles/2017/01/01/what-is-xsl-fo/[XSL-FO] stylesheet. A processing engine (Apache FOP) interprets the stylesheet and generates the PDF. +Metanorma generates PDF output from XML. The styling comes from an https://www.xml.com/articles/2017/01/01/what-is-xsl-fo/[XSL-FO] stylesheet. A processing engine (Apache FOP) interprets the stylesheet and generates the PDF. *Microsoft Word* @@ -84,8 +84,10 @@ Metanorma can also generate a `.doc` Word output. Metanorma does not output `.do Standards documents require collaboration and every SDO has its own process for reviews. Metanorma does support authors and reviewers by providing metadata that indicate in which phase the document is in and who reviewed it. You can add your remarks to a document with comments or create a to-do if you want someone to act. == Publication -Once you and your reviewers agree that the standard is ready for publishing, you send it to your standard developing organization (SDO). The SDO will publish your document in their preferred channels, such as online or print. +Once you and your reviewers agree that the standard is ready for publishing, you send it to your standard developing organization (SDO). The SDO will publish your document in their preferred channels, such as online or print. Before we dive into AsciiDoc, let's summarize what we've covered so far. -link:/learn/lessons/lesson-1-3/[Start next lesson »] ++++ +
Start next lesson »
++++ diff --git a/learn/lessons/lesson-1-3.adoc b/learn/lessons/lesson-1-3.adoc index 1436aeaa..c62da0e4 100644 --- a/learn/lessons/lesson-1-3.adoc +++ b/learn/lessons/lesson-1-3.adoc @@ -8,10 +8,12 @@ Let’s recap what we’ve learned so far: * You need to render documents to have a correct visible output. The appearance is controlled in a stylesheet. * Metanorma is an umbrella term for several things and consists of: + The Metanorma toolchain, document models and a XML schema of these document models. -* Metanorma documents use Metanorma AsciiDoc markup +* Metanorma documents use Metanorma AsciiDoc markup * When you want to generate an output, the AsciiDoc document is converted into XML in order to be checked against the XML schema. -* If the document is valid, Metanorma generates an HTML, PDF and Microsoft Word (`.doc`) output. +* If the document is valid, Metanorma generates an HTML, PDF and Microsoft Word (`.doc`) output. Now that we have covered the fundamentals, let’s have a look at AsciiDoc. -link:/learn/lessons/lesson-2/[Start next lesson »] ++++ +
Start next lesson »
++++ diff --git a/learn/lessons/lesson-1.adoc b/learn/lessons/lesson-1.adoc index ee22c380..b89ba8a4 100644 --- a/learn/lessons/lesson-1.adoc +++ b/learn/lessons/lesson-1.adoc @@ -6,8 +6,10 @@ title: Introduction to Metanorma Before we dive into using the Metanorma toolchain, let’s cover the basic ideas you need to understand to work with Metanorma. In this lesson you will learn: * What Metanorma is -* The differences between Word and Metanorma +* The differences between Word and Metanorma * The paradigms “What you see is what you get” vs. “What you see is what you mean” * What the Metanorma workflow looks like from document creation to publication -link:/learn/lessons/lesson-1-1/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-1.adoc b/learn/lessons/lesson-2-1.adoc index 6c502e40..5501d56d 100644 --- a/learn/lessons/lesson-2-1.adoc +++ b/learn/lessons/lesson-2-1.adoc @@ -6,14 +6,14 @@ exercise: include_relative /exercises.adoc :page-liquid: //include::/author/topics/metadata.adoc[tag=tutorial] -The header contains information about the document (metadata). You specify these metadata by using predefined document attributes, that look like this: `:document-attribute:`. Most of the attributes take a value, while others are simple flags without a value, like `:draft:`. +The header contains information about the document (metadata). You specify these metadata by using predefined document attributes, that look like this: `:document-attribute:`. Most of the attributes take a value, while others are simple flags without a value, like `:draft:`. Some of the metadata will be visible in your document, such as `:title:`, while others are not visible but still affect how your document is generated. The order of attributes doesn’t matter to Metanorma. You can specify metadata about: * Authors: Issuing organization, authors, and their location * Document info: Language, document stages (draft, published, etc.) copyright holder, etc. -* Dates: Draft dates, revision dates, publishing date, copyright year, etc. +* Dates: Draft dates, revision dates, publishing date, copyright year, etc. * Identifiers: Document numbers, ISBNs, URIs (Uniform Resource Identifiers) NOTE: Other metadata influence how the document is generated and should only be used by advanced users. Often, they will require familiarity with your organization's structures and processes. @@ -29,7 +29,7 @@ Here’s an example: :language: en :mn-document-class: ogc <4> :technical-committee: Committee name <5> -:fullname: Your Name <6> +:fullname: Your Name <6> :fullname_2: Co-Authors Name :address: Address line 1+ \ <7> Zip code + \ @@ -42,15 +42,17 @@ Country <1> A document always begins with the document title. <2> `:docnumber:` defines the formal number of the document. <3> `:doctype:` defines the type of document, for example standard, report, guide, etc. The allowed values for this attribute are specific to each SDO. -<4> `:mn-document-class:` indicates the Metanorma flavor the document should be checked against. +<4> `:mn-document-class:` indicates the Metanorma flavor the document should be checked against. <5> The committee responsible for the document -<6> The author’s name. You can add co-authors by appending the attribute with a number: `_2`, `_3`, and so on. -<7> When you add an address that contains multiple lines, end each line except for the last with `+ \`. Alternatively, you can enter each line into its own attribute, such as `:street:`, `:postcode:`, `:city:`, `:country:`. -<8> `:draft:` renders comments as well. The attribute does not take any values: it is either present or not. +<6> The author’s name. You can add co-authors by appending the attribute with a number: `_2`, `_3`, and so on. +<7> When you add an address that contains multiple lines, end each line except for the last with `+ \`. Alternatively, you can enter each line into its own attribute, such as `:street:`, `:postcode:`, `:city:`, `:country:`. +<8> `:draft:` renders comments as well. The attribute does not take any values: it is either present or not. <9> `mn-output-extensions` specifies the generated outputs. It can take several values that must be comma-delimited. == Practice time {% include_relative /exercises.adoc content="exercise-2-1" %} -link:/learn/lessons/lesson-2-2/[Start next lesson »] ++++ +
Start next lesson »
++++ diff --git a/learn/lessons/lesson-2-2.adoc b/learn/lessons/lesson-2-2.adoc index 0f047daf..a12bb947 100644 --- a/learn/lessons/lesson-2-2.adoc +++ b/learn/lessons/lesson-2-2.adoc @@ -4,8 +4,8 @@ title: Sections --- :page-liquid: -Sections define hierarchy levels in your document and are equivalent to chapters. The document title is the highest section and is created by prepending a `=` sign in front of the heading. If you want to go one level deeper in the hierarchy, add another `=`. -Here’s an example: +Sections define hierarchy levels in your document and are equivalent to chapters. The document title is the highest section and is created by prepending a `=` sign in front of the heading. If you want to go one level deeper in the hierarchy, add another `=`. +Here’s an example: [source, AsciiDoc] ---- @@ -38,18 +38,18 @@ A typical Metanorma document can contain the following sections: * Normative references * Terms and definitions * Definitions -* Clauses +* Clauses * Symbols and abbreviated terms * Bibliography * Annex To successfully validate a document, the compiler needs to know what sections are in the document. Metanorma relies on these predefined section titles to check them against the document model. However, not all sections need an identifier, for example, your ordinary content sections fall under the category of _clause section_, and are not further standardized. -NOTE: Each organization is based on the standard document model but they can omit sections or make them mandatory, if they choose to. For example, only NIST uses the acknowledgments section, whereas other SDOs do not require it. Flavours may overrule these pre-defined section titles with titles of their own, or may choose not to recognise at least some of them as special sections. Check the https://www.metanorma.org/flavors/[flavor documentation] for more details on how your SDO uses Metanorma. +NOTE: Each organization is based on the standard document model but they can omit sections or make them mandatory, if they choose to. For example, only NIST uses the acknowledgments section, whereas other SDOs do not require it. Flavours may overrule these pre-defined section titles with titles of their own, or may choose not to recognise at least some of them as special sections. Check the https://www.metanorma.org/flavors/[flavor documentation] for more details on how your SDO uses Metanorma. == Deviating section titles -If you want to use a different title or create a document in a language other than English, you need to add metadata in square brackets to ensure that sections are recognized. Plain AsciiDoc already provides some https://docs.asciidoctor.org/asciidoc/latest/sections/section-ref/#section-styles[section metadata] that Metanorma uses for document validation: +If you want to use a different title or create a document in a language other than English, you need to add metadata in square brackets to ensure that sections are recognized. Plain AsciiDoc already provides some https://docs.asciidoctor.org/asciidoc/latest/sections/section-ref/#section-styles[section metadata] that Metanorma uses for document validation: * `[abstract]` * `[acknowledgments]` @@ -95,13 +95,15 @@ There are also some Metanorma-specific section identifiers, that follow the synt <1> This section is an introduction but the compiler can not recognize it because it deviates from plain `== Introduction`. The `preface` attribute ensures that the document structure is still valid. <2> The `Normative references` section contains references to related standards. The compiler needs the `[bibliography]` tag, so that it renders the reference correctly. <3> Use the `heading` tag to assign section types specific to Metanorma. -<4> Here, the appendix is called “Annex”, and needs the `appendix` tag to define what kind of section it is. You can specify if a section is normative or informative by adding the `obligation` identifier after the section identifier. +<4> Here, the appendix is called “Annex”, and needs the `appendix` tag to define what kind of section it is. You can specify if a section is normative or informative by adding the `obligation` identifier after the section identifier. -== Practice time +=== Practice time {% include_relative /exercises.adoc content="exercise-2-2" %} We’ve built the basic structure of a Metanorma document. Let’s add some content to our document in the next lesson. -link:/learn/lessons/lesson-2-3-1/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-3-1.adoc b/learn/lessons/lesson-2-3-1.adoc index ed5e99c1..60749a87 100644 --- a/learn/lessons/lesson-2-3-1.adoc +++ b/learn/lessons/lesson-2-3-1.adoc @@ -26,7 +26,7 @@ The main changes compared to the previous edition are: == Ordered lists -Ordered lists are invoked by beginning the line with a dot `.`. The list items are numbered automatically. The default list arabic numbers but can vary depending on the stylesheet of your organization. +Ordered lists are invoked by beginning the line with a dot `.`. The list items are numbered automatically. The default list arabic numbers but can vary depending on the stylesheet of your organization. [source, AsciiDoc] ---- @@ -37,9 +37,9 @@ Ordered lists are invoked by beginning the line with a dot `.`. The list items a == Definition lists -Definition lists (also called https://docs.asciidoctor.org/asciidoc/latest/lists/description/[description lists] pair a term and a description together. They are often used in a "Definitions" section to define units or terms. Definition lists can appear in other sections as well, *except* for the Terms section, which provides a special syntax for defining terms. +Definition lists (also called https://docs.asciidoctor.org/asciidoc/latest/lists/description/[description lists] pair a term and a description together. They are often used in a "Definitions" section to define units or terms. Definition lists can appear in other sections as well, *except* for the Terms section, which provides a special syntax for defining terms. -Definition lists follow the syntax of: +Definition lists follow the syntax of: ---- `term:: Definition` ---- @@ -56,10 +56,12 @@ stem:[m_S]:: is the mass, in grams, of the test sample. NOTE: `\stem:[]` is used for mathematical formatting, and results in italics. So `stem:[w]` is an italic w, _w_; `\stem:[m_D]` is an italic m with a D subscript: _m~D~_. -== Practice time +=== Practice time {% include_relative /exercises.adoc content="exercise-2-3-1" %} Great work! Let’s have a look at term definitions in the next lesson. -link:/learn/lessons/lesson-2-3-2/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-3-2.adoc b/learn/lessons/lesson-2-3-2.adoc index e93b892f..7c72c297 100644 --- a/learn/lessons/lesson-2-3-2.adoc +++ b/learn/lessons/lesson-2-3-2.adoc @@ -4,7 +4,7 @@ title: Term definitions --- :page-liquid: -If you want to cite a term throughout the standard, include it in the terms and definitions section. Term definitions vary from definition lists, as they are more granular and provide metadata to mark features such as alternative terms or deprecated terms. +If you want to cite a term throughout the standard, include it in the terms and definitions section. Term definitions vary from definition lists, as they are more granular and provide metadata to mark features such as alternative terms or deprecated terms. Let’s have a look at a term entry: [source, AsciiDoc] @@ -15,12 +15,12 @@ Let’s have a look at a term entry: collection of data, published or curated by a single agent, and available for access or download in one or more formats <3> -=== feature +=== feature alt:[characteristic] <4> deprecated:[character] <5> domain:[software] <6> -abstraction of real world phenomena +abstraction of real world phenomena [.source] <7> <> @@ -32,10 +32,10 @@ term:[dataset] which contains GPS coordinates. <9> <1> The start of the terms and definitions section <2> The term that should be defined is marked as a subheading using three equal signs. `===`. <3> Definition for the term. If a term has macros, like `deprecated:[]`, the term definition is the first paragraph after the macros. -<4> `alt:[]` indicates an alternative term. +<4> `alt:[]` indicates an alternative term. <5> The term `feature` supersedes `character`. To document the old term, use the annotation `deprecated:[term]`. <6> Terms that do not obviously belong to a certain domain can be annotated with `domain:[]`. -<7> The `[.source]` attribute indicates that a citation follows, indicating where the term definition has been taken from. Make sure to include the dot `.` before source, so that the citation will be rendered correctly. +<7> The `[.source]` attribute indicates that a citation follows, indicating where the term definition has been taken from. Make sure to include the dot `.` before source, so that the citation will be rendered correctly. <8> If you provide an example, use the `[example]` attribute so that it renders according to the styling rules of your SDO. <9> `term:[]` cites the previously introduced term. @@ -46,4 +46,6 @@ term:[dataset] which contains GPS coordinates. <9> The next type of block we will cover are tables. -link:/learn/lessons/lesson-2-3-3/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-3-3.adoc b/learn/lessons/lesson-2-3-3.adoc index de46f80e..f78fc4df 100644 --- a/learn/lessons/lesson-2-3-3.adoc +++ b/learn/lessons/lesson-2-3-3.adoc @@ -14,16 +14,16 @@ Tables are a useful tool to collect and display measured data. As AsciiDoc is al |=== <3> |Cell in column 1, header row |Cell in column 2, header row <4> -|Cell in column 1, row 2 +|Cell in column 1, row 2 |Cell in column 2, row 2 <5> |=== <6> ---- -<1> Attribute that specifies the table. `cols=”x,x”` tells the compiler that there are two columns. `[cols="1,1"]` The numbers specify the amount of spacing. For example, `[cols="4,2,4"]` would define three columns. The first and last column’s width would be four times the relative width and the middle column would be half as broad. This attribute is optional. +<1> Attribute that specifies the table. `cols=”x,x”` tells the compiler that there are two columns. `[cols="1,1"]` The numbers specify the amount of spacing. For example, `[cols="4,2,4"]` would define three columns. The first and last column’s width would be four times the relative width and the middle column would be half as broad. This attribute is optional. NOTE: In typical AsciiDoc, `[cols="3"]` is considered a shorthand to `[cols="1,1,1"]`, but this is not supported in Metanorma AsciiDoc. -<2> You can add a table title by beginning the line with a dot `.`. Make sure that there is no space between the dot and the first word of the heading. +<2> You can add a table title by beginning the line with a dot `.`. Make sure that there is no space between the dot and the first word of the heading. <3> Starting delimiter `|===` -<4> The first line after the delimiter is the header row. To add a column, add a vertical bar `|` before the text that should be in the column. +<4> The first line after the delimiter is the header row. To add a column, add a vertical bar `|` before the text that should be in the column. <5> When you use the `[cols]` attribute, columns in the same row can appear on different lines of AsciiDoc text; otherwise, they need to all be on the same line of text, like in <4>. <6> Closing delimiter `|===` @@ -33,4 +33,6 @@ NOTE: In typical AsciiDoc, `[cols="3"]` is considered a shorthand to Let’s look at inserting images next. -link:/learn/lessons/lesson-2-3-4/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-3-4.adoc b/learn/lessons/lesson-2-3-4.adoc index 548a49be..db523121 100644 --- a/learn/lessons/lesson-2-3-4.adoc +++ b/learn/lessons/lesson-2-3-4.adoc @@ -17,12 +17,12 @@ image::images/input_output_diagram.png[UML diagram of inputs and outputs] <3> [%key] <4> input:: What goes into a process <5> -Output:: Result of the inpput's transformation +Output:: Result of the inpput's transformation ---- <1> Anchor for references <2> Image title -<3> Image macro `image::path/file.jpg[alt text]`. If you don’t want to include alt text, you still need to append empty square brackets at the end of the macro. +<3> Image macro `image::path/file.jpg[alt text]`. If you don’t want to include alt text, you still need to append empty square brackets at the end of the macro. <4> [%key] indicates that the image has a key. <5> Key entries @@ -32,4 +32,6 @@ Output:: Result of the inpput's transformation Let’s look at admonitions next. -link:/learn/lessons/lesson-2-3-5/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-3-5.adoc b/learn/lessons/lesson-2-3-5.adoc index f50fdf78..82c12c56 100644 --- a/learn/lessons/lesson-2-3-5.adoc +++ b/learn/lessons/lesson-2-3-5.adoc @@ -14,7 +14,7 @@ Start a new line with the signal word in all caps and a colon and write your adm .Example for an inline note [source, AsciiDoc] ---- -NOTE: Advice on when to use which signal word is specified in ANSI Z535.6. +NOTE: Advice on when to use which signal word is specified in ANSI Z535.6. ---- == Block admonitions @@ -44,18 +44,20 @@ The style can be any one of the admonition labels: === Metanorma-specific admonitions -Metanorma adds two more signal words: "Safety precautions" and "Danger". Since they are not standard AsciiDoc functionality, you'll need to mark them with a `type` attribute like this: +Metanorma adds two more signal words: "Safety precautions" and "Danger". Since they are not standard AsciiDoc functionality, you'll need to mark them with a `type` attribute like this: [source, AsciiDoc] ==== [type=danger] -DANGER: Do perform maintenance tasks while the machine is still operating. +DANGER: Do perform maintenance tasks while the machine is still operating. ==== -== Practice time +=== Practice time {% include_relative /exercises.adoc content="exercise-2-3-5" %} Great progress so far! Let's look at code samples in the next lesson. -link:/learn/lessons/lesson-2-3-6/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-3-6.adoc b/learn/lessons/lesson-2-3-6.adoc index f761ad76..05fedadb 100644 --- a/learn/lessons/lesson-2-3-6.adoc +++ b/learn/lessons/lesson-2-3-6.adoc @@ -15,7 +15,7 @@ AsciiDoc supports code samples using the `[source]` attribute before a new block puts "Hello, world." <4> %w{a b c}.each do |x| puts x -end +end ==== <5> ------ @@ -29,6 +29,8 @@ end {% include_relative /exercises.adoc content="exercise-2-3-6" %} -We’re done with blocks - good job! The next lesson covers inline markup. +We’re done with blocks - good job! The next lesson covers inline markup. -link:/learn/lessons/lesson-2-4/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-3.adoc b/learn/lessons/lesson-2-3.adoc index 0cd52bde..5008d630 100644 --- a/learn/lessons/lesson-2-3.adoc +++ b/learn/lessons/lesson-2-3.adoc @@ -5,12 +5,12 @@ title: Blocks :page-liquid: Information that forms a logical segment, such as a paragraph or a list, is called a block. -Most blocks start and end with a https://asciidoctor.org/docs/asciidoc-writers-guide/#delimited-blocks[delimiter] which is a matching sequence of characters. The delimiters tell the compiler that the text they contain belongs together. +Most blocks start and end with a https://asciidoctor.org/docs/asciidoc-writers-guide/#delimited-blocks[delimiter] which is a matching sequence of characters. The delimiters tell the compiler that the text they contain belongs together. .Examples for different blocks [source, AsciiDoc] ------ -I’m a paragraph and I don’t need a block delimiter. +I’m a paragraph and I don’t need a block delimiter. <1> . I’m a list item and also do not need a delimiter . I’m the second list item @@ -45,5 +45,5 @@ There are many types of blocks in AsciiDoc, such as: * Reviewer Notes -Let’s look at lists in the next lesson. +Let’s look at lists in the next lesson. //Button \ No newline at end of file diff --git a/learn/lessons/lesson-2-4-1.adoc b/learn/lessons/lesson-2-4-1.adoc index 987e3b0f..b36a49e9 100644 --- a/learn/lessons/lesson-2-4-1.adoc +++ b/learn/lessons/lesson-2-4-1.adoc @@ -7,16 +7,16 @@ title: Text markup == Text formatting //include::/author/topics/inline_markup/text_formatting.adoc[tag=tutorial,leveloffset=+2] -The simplest form of inline markup is to emphasize text. +The simplest form of inline markup is to emphasize text. AsciiDoc allows you to: -* Make words *bold* using asterisks -* _Italicise_ words with underscores +* Make words *bold* using asterisks +* _Italicise_ words with underscores * Apply `monospacing` using backticks * Superscript and subscript characters (like CO~2~ or x^4^) [source, AsciiDoc] ----- +---- *bold* _italic_ `monospace` @@ -31,7 +31,7 @@ Metanorma extends these simple formats with: * Underline text ([underline]#underline text#) [source, AsciiDoc] ----- +---- [strike]#strike through text# [smallcap]#small caps text# [underline]#underline text# @@ -42,7 +42,7 @@ Metanorma extends these simple formats with: Metanorma also supports automatic character replacements, for example the copyright symbol © can be entered using `(C)`. Metanorma AsciiDoc also recognises HTML and XML character references, and decimal and hexadecimal Unicode code points. -For more information about automatic character replacements, see https://docs.asciidoctor.org/asciidoc/latest/subs/replacements/[the AsciiDoc documentation]. +For more information about automatic character replacements, see https://docs.asciidoctor.org/asciidoc/latest/subs/replacements/[the AsciiDoc documentation]. == Footnotes //include:://author/topics/inline_markup/footnotes.adoc[tag=tutorial] @@ -85,10 +85,12 @@ footnote -- ---- -== Practice time +=== Practice time {% include_relative /exercises.adoc content="exercise-2-4-1" %} Let’s look at a more advanced form of inline formatting: index entries. -link:/learn/lessons/lesson-2-4-2/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-4-2.adoc b/learn/lessons/lesson-2-4-2.adoc index 404cbe54..11b5796e 100644 --- a/learn/lessons/lesson-2-4-2.adoc +++ b/learn/lessons/lesson-2-4-2.adoc @@ -35,4 +35,6 @@ was to carry Excalibur (((Sword, Broadsword, Excalibur))). <2> In the next lesson, we will cover references and links. -link:/learn/lessons/lesson-2-4-3/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-4-3.adoc b/learn/lessons/lesson-2-4-3.adoc index 1f76d071..c22ae2de 100644 --- a/learn/lessons/lesson-2-4-3.adoc +++ b/learn/lessons/lesson-2-4-3.adoc @@ -31,7 +31,7 @@ Download the latest link:downloads/report.pdf[Report]! To reference an *external* source: . Paste the URL into the document. -. Add link text in square brackets after the URL (optional) `URL[Link text]`. +. Add link text in square brackets after the URL (optional) `URL[Link text]`. + .Example of an external link [source, AsciiDoc] @@ -41,7 +41,7 @@ http://www.iso.org/[International Organization for Standardization]. == Metadata references -Every document contains a set of metadata to describe the document. You can insert a metadata reference by putting the attribute in curly braces `{attribute}`. The reference will be replaced with the value in the rendered output. +Every document contains a set of metadata to describe the document. You can insert a metadata reference by putting the attribute in curly braces `{attribute}`. The reference will be replaced with the value in the rendered output. [source, AsciiDoc] ---- @@ -57,14 +57,14 @@ This document was prepared by Technical Committee ISO/TC {technical-committee-nu //create new screenshots and update example To link to an important section, table, figure, formula, or list item in your document: -. Set an anchor using double square brackets before the content you want to reference: `\[[anchor]]`. +. Set an anchor using double square brackets before the content you want to reference: `\[[anchor]]`. + .Example for an anchor preceding an image [source, AsciiDoc] ---- [[figureC-1]] -.Typical gelatinization curve -image::images/rice_image2.png[Image of the gelatinization curve] +.Typical gelatinization curve +image::images/rice_image2.png[Image of the gelatinization curve] ---- + .Rendered image caption @@ -89,7 +89,7 @@ image::/assets/author/learn/references_img_target.jpg[] // Include in Auto Numbering topic?? === Auto-numbering of references -Metanorma automatically numbers and names references; because they are autonumbered, they will be renumbered automatically if you insert any new text of the same type. +Metanorma automatically numbers and names references; because they are autonumbered, they will be renumbered automatically if you insert any new text of the same type. Since the markup will be converted into XML, the anchor must follow the https://www.w3.org/TR/xml-names11/[XML namespace conventions]. Therefore, an anchor name name must not contain: @@ -104,12 +104,12 @@ If you want to learn more about the technical aspects of cross-references, read //include::/author/topics/sections/entering_bib.adoc[tag=tutorial] Most standard documents contain two sections with bibliographic references, namely the “normative references” and the “bibliography” (informative references). -Every bibliographic section must be preceded by the style attribute `[bibliography]` so that bibliographic references are recognized as such. +Every bibliographic section must be preceded by the style attribute `[bibliography]` so that bibliographic references are recognized as such. == Entering a bibliographic entry To enter a reference entry: -. Start a new unordered list (`*`) item. +. Start a new unordered list (`*`) item. . Enter triple square brackets (`[[[]]]`) which contain: + * The anchor name used to reference this entry @@ -122,19 +122,19 @@ To enter a reference entry: * [[[anchor,document identifier or reference tag]]], _reference list text_ ---- -. After the triple brackets, you may include the reference text in italics, for example the title of the document. +. After the triple brackets, you may include the reference text in italics, for example the title of the document. + -NOTE: Metanorma uses https://www.relaton.org/[Relaton] to link:author/concepts/automatic-reference-lookup.adoc[automatically fetch resource descriptions] from the SDO's web site. If Metanorma recognizes a document identifier, it will overwrite any title you provide with the authoritative title of the reference. +NOTE: Metanorma uses https://www.relaton.org/[Relaton] to link:author/concepts/automatic-reference-lookup.adoc[automatically fetch resource descriptions] from the SDO's web site. If Metanorma recognizes a document identifier, it will overwrite any title you provide with the authoritative title of the reference. == Referencing a bibliographic entry -To cite an entry from your bibliography:app-name: +To cite an entry from your bibliography:app-name: . Enter the anchor name like this: `\<>`. . To specify a location within the cited document, you can add https://www.metanorma.org/author/topics/document-format/bibliography/#localities[localities] in the brackets like so: `\<>`. == Bibliography example -The following code sample illustrates how a bibliography section looks like in AsciiDoc Metanorma. +The following code sample illustrates how a bibliography section looks like in AsciiDoc Metanorma. .Example for a bibliography section [source, AsciiDoc] @@ -151,10 +151,12 @@ Gets rendered as: * ISO 6540:1980. _Maize — Determination of moisture content (on milled grains and on whole grains)_ -== Practice time +=== Practice time {% include_relative /exercises.adoc content="exercise-2-4-3" %} Let’s summarize what we’ve learnt so far. -link:/learn/lessons/lesson-2-5/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-4.adoc b/learn/lessons/lesson-2-4.adoc index 33ea812a..f9019ac9 100644 --- a/learn/lessons/lesson-2-4.adoc +++ b/learn/lessons/lesson-2-4.adoc @@ -15,4 +15,6 @@ To annotate single words, you use inline markup. The markup encloses the word(s) Let’s look at these features in the following lessons. -link:/learn/lessons/lesson-2-4-1/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2-5.adoc b/learn/lessons/lesson-2-5.adoc index cebc1ce1..efb50683 100644 --- a/learn/lessons/lesson-2-5.adoc +++ b/learn/lessons/lesson-2-5.adoc @@ -9,16 +9,18 @@ We’ve covered a lot of ground, so here is a quick summary for you: * A Metanorma document consists of several predefined sections. The document model of your organization dictates which are optional and which are mandatory. Sections are invoked using equal signs `=`. * Blocks are entities that belong together, such as paragraphs, lists, tables, etc. Paragraphs and lists do not need to be marked by delimiters. The remaining block types begin and end with a delimiter, for example four dashes `----`. * Inline markup is used for text formatting and references. You can reference: -** an external source (`URL[Link text]`) +** an external source (`URL[Link text]`) ** Metadata (`{attribute}`) ** Places in the document by setting an anchor (`[[anchor-id]]`) and referencing the anchor (`<>`) -** Bibliographic entries + +** Bibliographic entries + [source, AsciiDoc] ---- * [[[anchor,document identifier or reference tag]]], _reference list text_ <> ---- -You did a great job so far! Let’s talk about reviewing documents in the next lesson. +You did a great job so far! Let’s talk about reviewing documents in the next lesson. -link:/learn/lessons/lesson-3/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-2.adoc b/learn/lessons/lesson-2.adoc index fdcc215b..7f9e5259 100644 --- a/learn/lessons/lesson-2.adoc +++ b/learn/lessons/lesson-2.adoc @@ -3,11 +3,11 @@ layout: learn title: Editing a Metanorma document - Introduction to AsciiDoc --- [[learning-objectives-2]] -Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. +Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. In this lesson, you will learn: -* What AsciiDoc is +* What AsciiDoc is * Which elements a typical Metanorma document contains * How to write and format text with AsciiDoc @@ -17,7 +17,7 @@ In this lesson, you will learn: Each Metanorma document is written in AsciiDoc, a markup language that annotates text with processing instructions for layout. Since AsciiDoc only consists of text, you can use any editor to create AsciiDoc files (`.adoc` files). AsciiDoc is very similar to Markdown or Wiki formatting but provides more precise markup for creating text documents, for example to create a bibliography section or an index. -Because Metanorma fulfills the markup requirements of SDOs, Metanorma extends plain AsciiDoc. This version of AsciiDoc is called Metanorma AsciiDoc. +Because Metanorma fulfills the markup requirements of SDOs, Metanorma extends plain AsciiDoc. This version of AsciiDoc is called Metanorma AsciiDoc. An AsciiDoc document consists of different levels of granularity: @@ -31,10 +31,12 @@ We will have a look at these different levels of markup in the following lessons === Prerequisites -* https://www.metanorma.org/install/[Install Metanorma] +* link:/install/[Install Metanorma] + -TIP: Use Metanorma in Docker to get started faster. -* Download the https://github.com/metanorma/metanorma-tutorial[Metanorma tutorial project]. +TIP: Use Metanorma in Docker to get started faster. +* Download the https://github.com/metanorma/metanorma-tutorial[Metanorma tutorial project]. -link:/learn/lessons/lesson-2-1/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-3-1.adoc b/learn/lessons/lesson-3-1.adoc index 5a357ffd..3a3ce913 100644 --- a/learn/lessons/lesson-3-1.adoc +++ b/learn/lessons/lesson-3-1.adoc @@ -19,7 +19,7 @@ for the document(s). To create a comment: . Define the start of the comment by creating an anchor `\[[start]]`. -. Define where the comment should end by creating an anchor `\[[end]]` (optional). +. Define where the comment should end by creating an anchor `\[[end]]` (optional). . Add the comments metadata: `[reviewer="Your Name",date=YYYYMMDDT0000,from=start,to=end]` + The `date` and `to` attributes are optional. The timestamp in the `date` attribute is optional, too. The `from` and `to` elements can be bookmarks which cover no space. . Begin the comment block using four asterisks `\****`. @@ -60,10 +60,12 @@ This is also treated as a reviewer note ==== ---- -== Practice time +=== Practice time {% include_relative /exercises.adoc content="exercise-3-1" %} Now that we've commented on the content, let's create a draft of the document. -link:/learn/lessons/lesson-3-2/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-3-2.adoc b/learn/lessons/lesson-3-2.adoc index 4ee7ebdf..e8de2221 100644 --- a/learn/lessons/lesson-3-2.adoc +++ b/learn/lessons/lesson-3-2.adoc @@ -10,7 +10,7 @@ To render a draft that your peers should review, you need to add these metadata * `:status: draft` Defines the current document stage. + NOTE: Some flavors, for example ISO, use `:docstage:` and a status code to indicate in what stage the document is. -To compile a Metanorma document you must enter the name of the application `Metanorma` and the document you want to compile `document.adoc`. +To compile a Metanorma document you must enter the name of the application `Metanorma` and the document you want to compile `document.adoc`. [source, shell] ---- @@ -29,4 +29,6 @@ With this command you trigger the Metanorma toolchain to: Now that you are familiar with the simplest way of creating a Metanorma document, let's look at different ways to compile documents in the next lesson. -link:/learn/lessons/lesson-4/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-3.adoc b/learn/lessons/lesson-3.adoc index 23b8a84d..0e3c6c17 100644 --- a/learn/lessons/lesson-3.adoc +++ b/learn/lessons/lesson-3.adoc @@ -3,10 +3,12 @@ layout: learn title: Reviewing Metanorma documents --- [[learning-objectives-3]] -Reviewing documents is an integral part of developing a standard. The best way to review a document, is to use a version control environment that supports comments as well, such as GitHub and its feature GitHub discussions. In case your organization does not use a git-based approach, Metanorma provides a comment functionality that lets you insert your remarks and create to dos. -In this lesson, you will learn: +Reviewing documents is an integral part of developing a standard. The best way to review a document, is to use a version control environment that supports comments as well, such as GitHub and its feature GitHub discussions. In case your organization does not use a git-based approach, Metanorma provides a comment functionality that lets you insert your remarks and create to dos. +In this lesson, you will learn: * How to add comments using AsciiDoc markup -* How to generate a draft using the command line. +* How to generate a draft using the command line. -link:/learn/lessons/lesson-3-1/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-4-1.adoc b/learn/lessons/lesson-4-1.adoc index fda9ab57..6842e7b2 100644 --- a/learn/lessons/lesson-4-1.adoc +++ b/learn/lessons/lesson-4-1.adoc @@ -9,11 +9,11 @@ To successfully compile a Metanorma document, the toolchain looks at: * Metadata: The title, document flavor, and document type. * Syntax: Is the entered AsciiDoc code correct? * Dependencies: Are all tools needed to compile the document installed? -* File references: Are any files referred to by the file being compiled, and is their path entered correctly, for example when you include images (`image::PATH[]`). Advanced AsciiDoc usage also allows a document to embed other AsciiDoc documents (`include::PATH[]`), and Metanorma extends this in advanced usage to external data sources. +* File references: Are any files referred to by the file being compiled, and is their path entered correctly, for example when you include images (`image::PATH[]`). Advanced AsciiDoc usage also allows a document to embed other AsciiDoc documents (`include::PATH[]`), and Metanorma extends this in advanced usage to external data sources. To compile a Metanorma document: -. On the command line, go to the folder where the document you want to compile is located. +. On the command line, go to the folder where the document you want to compile is located. . Enter the following command: + [source, shell] ---- @@ -26,7 +26,7 @@ With this command you trigger the Metanorma toolchain to: * Check the XML against the document model (XML schema) * Create HTML, PDF, and DOC output -You can also manipulate the way Metanorma compiles a document by setting flags. Flags are appended to the build command, like this: +You can also manipulate the way Metanorma compiles a document by setting flags. Flags are appended to the build command, like this: .Example of a build command with a flag [source, shell] @@ -38,8 +38,8 @@ You can use the following flags to manipulate the building process: * `-t`: Sets the flavor of the document + NOTE: Either define the flavor in the metadata using `mn-document-class` or use `-t flavor` -* `-x`: Sets the output format(s) of the document -* `-o`: Enter a path that the output should be saved to. +* `-x`: Sets the output format(s) of the document +* `-o`: Enter a path that the output should be saved to. To see the full list of possible build commands, open the Metanorma help on the command line. @@ -50,4 +50,6 @@ metanorma help compile Because you will often encounter problems during the compilation process, we'll cover how to troubleshoot very common errors next. -link:/learn/lessons/lesson-4-2/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-4-2.adoc b/learn/lessons/lesson-4-2.adoc index 3b5d071f..9862bdf5 100644 --- a/learn/lessons/lesson-4-2.adoc +++ b/learn/lessons/lesson-4-2.adoc @@ -6,15 +6,15 @@ title: Troubleshooting //include::/author/topics/troubleshooting.adoc[tag=tutorial,leveloffset=+2] -There can be many reasons why you can’t compile a Metanorma AsciiDoc document into the final output, but you can easily fix them when you are familiar with typical errors. +There can be many reasons why you can’t compile a Metanorma AsciiDoc document into the final output, but you can easily fix them when you are familiar with typical errors. -Metanorma tells you what’s wrong in the terminal while it is building the document. The errors are also stored in an Error file `.err` in the same directory where your original document is stored, so you can debug them later. +Metanorma tells you what’s wrong in the terminal while it is building the document. The errors are also stored in an Error file `.err` in the same directory where your original document is stored, so you can debug them later. == How to troubleshoot a document -The best way to troubleshoot a document is to break up the content in several parts to narrow down the location of the error. -Regardless of troubleshooting, it is a good practice to divide a document into sections. You can then compile each section separately, or compile several of them in order to locate the error easier. -For example, if you assume there could be some error in Foreword section and want to exclude it from being rendered, you can easily comment out the section. +The best way to troubleshoot a document is to break up the content in several parts to narrow down the location of the error. +Regardless of troubleshooting, it is a good practice to divide a document into sections. You can then compile each section separately, or compile several of them in order to locate the error easier. +For example, if you assume there could be some error in Foreword section and want to exclude it from being rendered, you can easily comment out the section. .Example for a modular document setup [source,Asciidoc] @@ -24,31 +24,31 @@ For example, if you assume there could be some error in Foreword section and wan `//include::sections/00-foreword.adoc[]` `include::sections/01-introduction.adoc[]` -`include::sections/02-scope.adoc[]` +`include::sections/02-scope.adoc[]` ... -- -=== Where to start troubleshooting? +=== Where to start troubleshooting? * *If the document did not compile:* + If Metanorma did not generate any visual output, you need to work with the errors in the terminal. If execution has aborted before the XML content could be finalised, the XML file is still output to disk, suffixed with `.xml.abort` rather than `.xml`, and you can use it to make sense of error messages. * *If the document did compile and generated visual output:* + -Have a look at the compiled output: Are there missing sections? Is the formatting different than what you expected? Sometimes you can catch errors by looking at the rendered document. After that, have a look at the errors on the terminal to pinpoint where things went wrong. +Have a look at the compiled output: Are there missing sections? Is the formatting different than what you expected? Sometimes you can catch errors by looking at the rendered document. After that, have a look at the errors on the terminal to pinpoint where things went wrong. //include::/author/topics/troubleshooting.adoc[tag=no-compile-markup,leveloffset=+1] === Markup errors -Metanorma can't compile a document, when required information is missing or there are markup errors. +Metanorma can't compile a document, when required information is missing or there are markup errors. -==== Header lacks required metadata +==== Header lacks required metadata Metanorma can't compile documents when the core metadata of a document are missing or incomplete. Metanorma will not render a document if one or more attributes are missing or contain unknown values: * Type of flavor `:mn-document-class:`, for example `iso, ietf, un, etc.` + -If the document flavor isn't specified in the header, it needs to be specified in the build command, or else the compilation will fail. +If the document flavor isn't specified in the header, it needs to be specified in the build command, or else the compilation will fail. * Document type `:doctype:`, for example `international standard` + -If the document type isn't specified in the header, it needs to be specified in the build command, or else the compilation will fail. +If the document type isn't specified in the header, it needs to be specified in the build command, or else the compilation will fail. * Metadata specific to your organization. Check the https://www.metanorma.org/flavors/[flavor documentation] to make sure you've entered the metadata correctly. @@ -87,7 +87,7 @@ If two or more cross-references have the same anchor, the document won't build a ... ---- -To solve this problem, rename the anchor. Check your document against any references for the anchor that you changed and update them. +To solve this problem, rename the anchor. Check your document against any references for the anchor that you changed and update them. //include::/author/topics/troubleshooting.adoc[tag=rendering-errors,leveloffset=+1] @@ -96,10 +96,10 @@ The main cause for rendering errors are markup errors which can lead to unexpect Some issues can be: ==== Title page is missing information -If your title page is missing completely, or only shows parts, check the document attributes in the header. If metadata, like the title, is missing, the document will be rendered faulty. +If your title page is missing completely, or only shows parts, check the document attributes in the header. If metadata, like the title, is missing, the document will be rendered faulty. ==== Document starts to look odd from one point onwards -AsciiDoc requires block delimiters for some block types, such as code samples and tables. The block delimiter consists of a minimum of four characters. If the number or type of block delimiters don't match, the compiler doesn't know where a block begins/ends. +AsciiDoc requires block delimiters for some block types, such as code samples and tables. The block delimiter consists of a minimum of four characters. If the number or type of block delimiters don't match, the compiler doesn't know where a block begins/ends. Look for the beginning of the issue, go to the markup, and check out the delimiting characters of the blocks. @@ -110,7 +110,7 @@ Look for the beginning of the issue, go to the markup, and check out the delimit [source,Asciidoc] === <1> image::../assets/image.png[] -=== +=== |== <2> |Name of Column 1 @@ -125,25 +125,27 @@ image::../assets/image.png[] ---- <1> The author wanted to demonstrate how to insert an image using AsciiDoc markup. However, the compiler will insert the image (if it exists) because of the missing `=`. -<2> The block delimiter is only three characters long, so the compiler will not render the table. +<2> The block delimiter is only three characters long, so the compiler will not render the table. <3> `|---` This delimiter is invalid. ==== Paragraphs look like code blocks If you ever see a paragraph rendered inside of a source block, you probably have left a white space at its beginning. Paragraphs cannot begin with any white space or they will be erroneously rendered as source blocks. ==== Missing images -If there are images missing, make sure that: +If there are images missing, make sure that: * The syntax is correct. Make sure you set the square brackets at the end, even if you don't want to use any attributes for the image. + ---- image::path/file.jpg[] ---- -* The path and the file extension are correct. If you used the https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/[`:imagesdir:` attribute] to set the image path, check if the path is correct. +* The path and the file extension are correct. If you used the https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/[`:imagesdir:` attribute] to set the image path, check if the path is correct. -== Practice time +=== Practice time {% include_relative /exercises.adoc content="exercise-4-2" %} Let’s recap what we’ve covered in this lesson. -link:/learn/lessons/lesson-4-3/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/learn/lessons/lesson-4-3.adoc b/learn/lessons/lesson-4-3.adoc index e0c500f0..58331690 100644 --- a/learn/lessons/lesson-4-3.adoc +++ b/learn/lessons/lesson-4-3.adoc @@ -5,7 +5,7 @@ title: Summary of lesson 4 Let's summarize what we've learnt in this lesson: -* To generate a Metanorma document, enter the following command: +* To generate a Metanorma document, enter the following command: + .Local installation [source, shell] @@ -29,21 +29,22 @@ docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma doc * More often than not, we encounter errors that we need to fix: ** Metadata errors: Provide all metadata that your organization mandates; include the flavor type and document type either in the header or in the build command. -** Markup errors: Make sure you've entered the correct syntax for blocks or inline macros and provided the correct filenames and paths. -** Reference errors: If a reference can't be resolved, make sure that the anchor name follows the naming rules; The anchor and the reference need to be identical. +** Markup errors: Make sure you've entered the correct syntax for blocks or inline macros and provided the correct filenames and paths. +** Reference errors: If a reference can't be resolved, make sure that the anchor name follows the naming rules; The anchor and the reference need to be identical. ** Bugs: Sometimes, when you can't solve an error, you might have discovered a bug. Feel free to raise an issue in your organization's repository on the https://github.com/Metanorma[Metanorma Github page]. -Great work! You've completed the Metanorma fundamentals tutorial! +Great work! You've completed the Metanorma fundamentals tutorial! -You're ready to create Metanorma documents on your own. -To get started, you can download a https://github.com/orgs/metanorma/repositories?q=mn-templates[template document]. +You're ready to create Metanorma documents on your own. +To get started, you can download a https://github.com/orgs/metanorma/repositories?q=mn-templates[template document]. Look up any flavor-specific rules in the the link:/flavors[flavor documentation]. ////// Maybe include a page after the tutorial where a user can type in their name and a certificate (PDF) will be generated + downloaded? :) -link:/">Finish» ++++ +
Finish»
+++ ////// diff --git a/learn/lessons/lesson-4.adoc b/learn/lessons/lesson-4.adoc index da5bb6ae..19ace9b3 100644 --- a/learn/lessons/lesson-4.adoc +++ b/learn/lessons/lesson-4.adoc @@ -4,10 +4,12 @@ title: Publishing a Metanorma Document --- [[learning-objectives-4]] -Once you are happy with your document, the next step is to generate an output to send your SDO for publishing. Since Metanorma poses some validity criteria for your document, it is normal to face some errors. Don’t worry, we will go through some common errors and teach you how to resolve them. +Once you are happy with your document, the next step is to generate an output to send your SDO for publishing. Since Metanorma poses some validity criteria for your document, it is normal to face some errors. Don’t worry, we will go through some common errors and teach you how to resolve them. In this lesson you will learn: * How to generate PDF, HTML, and Word output using the command line -* How to troubleshoot common errors +* How to troubleshoot common errors -link:/learn/lessons/lesson-4-1/[Start next lesson »] \ No newline at end of file ++++ +
Start next lesson »
++++ \ No newline at end of file diff --git a/nav-links.html b/nav-links.html index 1c5dee8f..572e55e0 100644 --- a/nav-links.html +++ b/nav-links.html @@ -8,19 +8,19 @@ {% include nav-page-link.html htmlclass="learn" url="/learn/" title="Learn" active_for_nested=true %} -{% include nav-page-link.html htmlclass="author" url="/author/" title="Docs" active_for_nested=true %} +{% include nav-page-link.html htmlclass="author" url="/author/" title="Author" active_for_nested=true %} {% include nav-page-link.html htmlclass="flavors" url="/flavors/" title="Flavors" active_for_nested=true %} - -{% include nav-page-link.html htmlclass="contribute" url="/contribute/" title="Contribute" active_for_nested=true %} --> + -{% include nav-page-link.html htmlclass="develop" url="/develop/" title="Develop" active_for_nested=true %} + - + {% include nav-page-link.html htmlclass="blog" url="/blog/" title="Blog" active_for_nested=true %} diff --git a/reference_docs/YAML_models/standoc_document_attributes.yaml b/reference_docs/YAML_models/standoc_document_attributes.yaml index 9494f139..a9f70c6f 100644 --- a/reference_docs/YAML_models/standoc_document_attributes.yaml +++ b/reference_docs/YAML_models/standoc_document_attributes.yaml @@ -84,7 +84,7 @@ document_attributes: description: | Name of YAML language template file. Use if you wish to output an standard in a language that’s not supported out of the box. - For more on how to customise localization, see link:/builder/topics/localization[Localization]. + For more on how to customise localization, see link:/develop/topics/localization[Localization]. language: tags: ["Languages and localization"] @@ -102,7 +102,7 @@ document_attributes: boilerplate-authority: tags: ["Languages and localization"] title: "Boilerplate authority" - description: "File containing predefined text of document, in Metanorma XML. The document predefined text needs to follow the structure described in link:/builder/topics/metadata-and-boilerplate#boilerplate[Predefined text]; compare examples of Metanorma predefined text files such as https://github.com/metanorma/metanorma-itu/blob/main/lib/asciidoctor/itu/boilerplate.xml[that in ITU]." + description: "File containing predefined text of document, in Metanorma XML. The document predefined text needs to follow the structure described in link:/develop/topics/metadata-and-boilerplate#boilerplate[Predefined text]; compare examples of Metanorma predefined text files such as https://github.com/metanorma/metanorma-itu/blob/main/lib/asciidoctor/itu/boilerplate.xml[that in ITU]." added_in_version: v1.3.15 #--- Document info ---#