diff --git a/.gitignore b/.gitignore index 2abc976a..80feb288 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,9 @@ _software/*/.git _software/*/docs _software/_*_repo +_software/metanorma-bipm/ +_software/metanorma-generic/ +_software/metanorma-iho/ _specs/*/ !_specs/*.* parent-hub @@ -11,3 +14,5 @@ _site/ .DS_Store .rubocop-https--* +.vscode/settings.json +Gemfile.lock \ No newline at end of file diff --git a/.lycheeignore b/.lycheeignore index 0c67672d..0f9bd00c 100644 --- a/.lycheeignore +++ b/.lycheeignore @@ -5,4 +5,8 @@ https://twitter.com/RiboseUS .*@viagenie.ca .*@.*example.com (ht|f)tps?://.*\.?example\.(com|org).* -ldap://.* \ No newline at end of file +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 diff --git a/Gemfile b/Gemfile index 45d72186..1748cf4a 100644 --- a/Gemfile +++ b/Gemfile @@ -26,7 +26,7 @@ group :jekyll_plugins do gem "jekyll-asciidoc" gem "jekyll-redirect-from" gem "git" - gem "jekyll-theme-open-project-helpers" + gem "jekyll-theme-open-project-helpers", "~> 2.1.9" gem "kramdown-parser-gfm" gem "kramdown-syntax-coderay" end diff --git a/README.adoc b/README.adoc index ecea3834..278dab79 100644 --- a/README.adoc +++ b/README.adoc @@ -46,7 +46,7 @@ IMPORTANT: Try to reduce such changes with careful planning, and never delete or . **Settle on flavor and markup abbreviations.** + - _Flavor abbreviation_ is _not_ typically the same as organization abbreviation; - usually it ends with “D”—e.g., M3AAWG is M3AAWG's flavor abbreviation. + usually it ends with "D"—e.g., M3AAWG is M3AAWG's flavor abbreviation. + IMPORTANT: The `--type` flag given to Metanorma-CLI is expected to reference the same flavor abbreviation in lowercase. - _Markup abbreviation_ usually takes the form of `Ascii`. @@ -60,7 +60,7 @@ IMPORTANT: The `--type` flag given to Metanorma-CLI is expected to reference the how sections are formatted, how references are formatted, any specifics about build, etc. - One or more pages offering _reference guides_: a complete list of custom document attributes - (either new attributes or attributes which behave differently compared to “base” Metanorma), + (either new attributes or attributes which behave differently compared to "base" Metanorma), a list of unsupported AsciiDoc features, etc. + [TIP] @@ -196,7 +196,7 @@ title: Write with Metanorma data_models: # (optional) - # Use for “experimental” flavors not ready for production. + # Use for "experimental" flavors not ready for production. experimental: yes ---- diff --git a/_config.yml b/_config.yml index 32d02dd4..d3248cfa 100644 --- a/_config.yml +++ b/_config.yml @@ -115,6 +115,11 @@ tag_namespaces: specs: audience: "Audience" completion_status: "Status" + docs: + content-type: 'Type of content' #Classification: Tutorial, How-to guide, Explanation, Reference; --> Useful for a migration to DITA? + reference_docs: + flavor: 'Flavor' + type: 'Type of content' # For example: Specification, Document Attributes, Document Structures, UML diagrams safe: false include: diff --git a/_layouts/author-docs.html b/_layouts/author-docs.html index 828cadc2..247f7737 100644 --- a/_layouts/author-docs.html +++ b/_layouts/author-docs.html @@ -19,6 +19,37 @@ - title: Metanorma AsciiDoc path: /topics/document-format/ description: Metanorma's general authoring guidance, flavor non-specific + + - title: Concepts + description: How Metanorma works and best practices + items: + - title: What is Metanorma? + path: /concepts/what_is_metanorma/ + - title: Is what you see what you get? + path: /concepts/wysiwyg_vs_wysiwym/ + - title: The Metanorma workflow + path: /concepts/metanorma_workflow/ + - title: What is AsciiDoc? + path: /concepts/intro_to_asciidoc/ + - title: Best practice - Organizing a Metanorma project + path: /concepts/best_practice_project_structure/ + - title: Auto numbering in Metanorma + path: /concepts/auto_numbering/ + - title: Automatic reference lookup using Relaton + path: /concepts/automatic-reference-lookup/ + + - title: New Metanorma Document + description: Creating a new Metanorma Document + path: /topics/creating_new_document/ + + - title: Editing Metanorma Documents + description: Metanorma's general authoring guidance, flavor non-specific + items: + - title: Adding Metadata + path: /topics/metadata/ + + - title: Sections + path: /topics/sections/ items: - title: Attributes path: /topics/document-format/meta-attributes/ @@ -30,14 +61,45 @@ path: /topics/document-format/xrefs/ - title: Concepts, terms and definitions path: /topics/document-format/section-terms/ + - title: Section Attributes + path: /topics/sections/section_attributes + - title: Table of Contents generated from Section Headings + path: /topics/sections/generated_toc/ + - title: Prefatory Sections + path: /topics/sections/introductions/ + - title: Terms and definitions + path: /topics/sections/terms_definitions/ + - title: Entering term definitions + path: /topics/sections/entering-terms/ - title: Bibliography - path: /topics/document-format/bibliography/ + path: /topics/sections/bibliography/ + - title: Entering bibliographic entries + path: /topics/sections/entering-bib/ + + - title: Blocks + path: /topics/blocks/ + items: + - title: Lists + path: /topics/blocks/lists/ + - title: Tables + path: /topics/blocks/tables/ + - title: Images + path: /topics/blocks/images/ + - title: Admonitions + path: /topics/blocks/admonitions/ + - title: Quotes + path: /topics/blocks/quotes/ + - title: Code Samples + path: /topics/blocks/code_samples/ - title: Diagrams path: /topics/document-format/diagrams/ - title: Indexing and table of contents path: /topics/document-format/indexes/ - title: Annotations path: /topics/document-format/annotations/ + path: /topics/blocks/diagrams/ + - title: Mathematical Expressions + path: /topics/blocks/math/ - title: Requirement, Recommendation, and Permission path: /topics/document-format/requirements/ items: @@ -47,10 +109,34 @@ path: /topics/document-format/requirements-modspec/ - title: Collections path: /topics/document-format/collections/ + path: /topics/blocks/requirements/ + - title: Passthrough to Metanorma XML and target formats + path: /topics/blocks/passthroughs/ + - title: Forms + path: /topics/blocks/forms/ + + - title: Inline Markup + path: /topics/inline_markup/ + items: + - title: Text formatting + path: /topics/inline_markup/text_formatting/ + - title: Footnotes + path: /topics/inline_markup/footnotes/ + - title: Links and Cross-references + path: /topics/inline_markup/links/ + - title: Index Terms + path: /topics/inline_markup/index_terms/ - title: Changes path: /topics/document-format/changes/ - title: Forms path: /topics/document-format/forms/ + path: /topics/inline_markup/changes/ + + - title: Languages and Localization + path: /topics/languages/ + + - title: Collections + path: /topics/collections/ - title: Automation path: /topics/automation/ @@ -59,34 +145,38 @@ path: /topics/automation/lutaml_uml/ - title: "Datamodel plugin" path: /topics/automation/datamodel/ - - title: "Yaml2Text plugin" + - title: Yaml2Text plugin path: /topics/automation/yaml_to_text/ - - title: "Json2Text plugin" + - title: Json2Text plugin path: /topics/automation/json_to_text/ - title: Building documents path: /topics/building/ items: - - title: Validation - path: /topics/building/validation/ - - title: Auto reference lookup - path: /topics/building/reference-lookup/ - - title: Output formats - path: /topics/building/output-formats/ - - title: Font management - path: /topics/building/font-management/ - - - title: Languages & localization - path: /topics/languages/ + - title: Automatically extracting information from Metanorma + path: /topics/automation/extraction_from_mn/ - - title: References - items: - - title: Document attributes - path: /ref/document-attributes/ - - title: AsciiMath support - path: /ref/asciimath/ - - title: AsciiDoc tips - path: /ref/asciidoc-tips/ + - title: Reviewing Documents + path: /topics/reviewing/ + + - title: Generating Output + path: /topics/output/ + items: + - title: Validation + path: /topics/output/validation/ + - title: Output formats + path: /topics/output/output-formats/ + - title: Font management + path: /topics/output/font-management/ + + - title: References + items: + - title: Document attributes + path: /ref/document-attributes/ + - title: AsciiDoc cheat sheet + path: /ref/asciidoc-tips/ + - title: AsciiMath support + path: /ref/asciimath/ - title: Background items: diff --git a/_layouts/bsi-flavor.adoc b/_layouts/bsi-flavor.adoc new file mode 100644 index 00000000..c7398d0a --- /dev/null +++ b/_layouts/bsi-flavor.adoc @@ -0,0 +1,42 @@ +--- +layout: flavor + +docs_title: Metanorma for BSI +title: Author BSI documents using Metanorma + +bsi_flavor: + title: BSI + private: true + markup_name: Metanorma for BSI + build: + cli_flags: "--type bsi -x html" + sample: + repo_url: https://github.com/metanorma/mn-samples-bsi + rendered_url: https://metanorma.github.io/mn-samples-bsi/ + implemented_by: metanorma-bsi + data_models: metanorma-model-bsi + docs_entry_points: + - path: ./authoring/ + title: guide + +base_url: /author/bsi + +navigation: + items: + - title: Get started + path: / + - title: Usage + path: /topics/ + items: + - title: Formats + path: /topics/formats/ + - title: Markup + path: /topics/markup/ + - title: Reference guides + path: /ref/ + items: + - title: Document attributes + path: /ref/document-attributes/ +--- + +{{ content }} diff --git a/_layouts/builder-docs.html b/_layouts/builder-docs.html index f812320e..c1b1b3a3 100644 --- a/_layouts/builder-docs.html +++ b/_layouts/builder-docs.html @@ -1,10 +1,10 @@ --- layout: docs-base html-class: docs-page -docs_title: Builder's documentation +docs_title: Developer documentation navigation: - base_url: /builder + base_url: /developer items: - title: Get started @@ -26,6 +26,8 @@ path: /topics/styling-output-html/ - title: Styling Microsoft Word output path: /topics/styling-output-msword/ + - title: Metadata and predefined text + path: /topics/metadata-and-boilerplate - title: References items: diff --git a/_layouts/home.html b/_layouts/home.html index c0524e46..1e7a4f76 100644 --- a/_layouts/home.html +++ b/_layouts/home.html @@ -25,6 +25,13 @@ - name: UN path: /author/un/ + - name: NIST + path: /author/nist/ + private: true + - name: BSI + path: /author/bsi/ + private: true + - name: BIPM description: BIPM standards path: /author/bipm/ @@ -39,6 +46,10 @@ description: Messaging, Malware and Mobile Anti-Abuse Working Group path: /author/m3aawg/ experimental: yes + - name: JIS + description: JIS standards + path: /author/jis/ + experimental: yes corporate: - name: MPFA diff --git a/_layouts/jis-flavor.adoc b/_layouts/jis-flavor.adoc new file mode 100644 index 00000000..d6c251ac --- /dev/null +++ b/_layouts/jis-flavor.adoc @@ -0,0 +1,71 @@ +--- +layout: flavor + +docs_title: Metanorma for JIS +title: Author JIS documents using Metanorma + +ieee_flavor: + implemented_by: metanorma-jis + data_models: metanorma-model-jis + title: JIS + title_org: JIS + title_org_full: Japanese Industrial Standards + markup_name: Metanorma for JIS + experimental: yes + build: + cli_flags: "--type jis -x html" + sample: + repo_url: https://github.com/metanorma/mn-samples-jis + rendered_url: https://metanorma.github.io/mn-samples-jis/ + docs_entry_points: + - path: ./topics/markup/ + title: General guide + +base_url: /author/jis + +navigation: + items: + - title: Get started + path: / + - title: Authoring guide + path: /authoring-guide/ + items: + - title: Terms used in this guide + path: /authoring-guide/terms/ + - title: Development process + path: /authoring-guide/process/ + - title: Metanorma AsciiDoc + path: /authoring-guide/metanorma-adoc/ + - title: New document + path: /authoring-guide/new-doc-template/ + - title: Setting metadata + path: /authoring-guide/metadata/ + - title: Sections + path: /authoring-guide/sections/ + - title: Block syntax + path: /authoring-guide/block-syntax/ + - title: Text formatting + path: /authoring-guide/text-formatting/ + - title: Cross references + path: /authoring-guide/cross-references/ + - title: Terms and definitions + path: /authoring-guide/terms-definitions/ + - title: Bibliographic references + path: /authoring-guide/bibliographic-references/ + - title: Samples + path: /sample/ + - title: Usage + path: /topics/ + items: + - title: Markup + path: /topics/markup/ + - title: Output formats + path: /topics/formats/ + - title: Reference guides + path: /ref/ + items: + - title: Document attributes + path: /ref/document-attributes/ +--- + +{{ content }} diff --git a/_layouts/nist-flavor.adoc b/_layouts/nist-flavor.adoc new file mode 100644 index 00000000..6ceb087e --- /dev/null +++ b/_layouts/nist-flavor.adoc @@ -0,0 +1,42 @@ +--- +layout: flavor + +docs_title: Metanorma for NIST +title: Author NIST documents using Metanorma + +nist_flavor: + title: NIST + private: true + markup_name: Metanorma for NIST + build: + cli_flags: "--type nist -x html" + sample: + repo_url: https://github.com/metanorma/mn-samples-nist + rendered_url: https://metanorma.github.io/mn-samples-nist/ + implemented_by: metanorma-nist + data_models: metanorma-model-nist + docs_entry_points: + - path: ./authoring/ + title: guide + +base_url: /author/nist + +navigation: + items: + - title: Get started + path: / + - title: Usage + path: /topics/ + items: + - title: Formats + path: /topics/formats/ + - title: Markup + path: /topics/markup/ + - title: Reference guides + path: /ref/ + items: + - title: Document attributes + path: /ref/document-attributes/ +--- + +{{ content }} diff --git a/_layouts/tutorial.html b/_layouts/tutorial.html new file mode 100644 index 00000000..deac62ad --- /dev/null +++ b/_layouts/tutorial.html @@ -0,0 +1,60 @@ +--- +layout: tutorial + +navigation: + base_url: /tutorials + items: + - title: Metanorma tutorial for beginners + path: / + + - title: Introduction to Metanorma + items: + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + + - title: Editing a Metanorma document + items: + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + + - title: Reviewing Metanorma documents + items: + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + + - title: Publishing a Metanorma document + items: + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ + - title: + path: /tutorials/template/ +--- + + +
+
+

{{ page.section-title }}

+
+ +
{{ content }}
+
diff --git a/_pages/author.adoc b/_pages/author.adoc index 53ee0af9..843107c3 100644 --- a/_pages/author.adoc +++ b/_pages/author.adoc @@ -5,14 +5,13 @@ article_header_title: Metanorma author's documentation html-class: overview redirect_from: - /overview/ - - /docs/ --- :page-liquid: == Why Metanorma? [.feature-list] -* Easy +++WYSIWYM+++ semantic authoring +* Easy +++WYSIWYM+++ semantic authoring with syntax based on AsciiDoc. * Validation of document contents against a set of style rules, @@ -29,3 +28,10 @@ redirect_from: +++
Get started
+++ +The Metanorma documentation covers all features you need to create your next standard document effortlessly. + +The documentation structure follows the Metanorma workflow, depicted below. +You'll find background information and best practice articles in the concepts section. If you need to quickly look up an attribute, head to the references section. + +.The Metanorma Workflow from start to finish +image::../assets/author/concepts/Metanorma_Workflow.png[The Metanorma workflow] \ No newline at end of file diff --git a/_pages/builder.adoc b/_pages/builder.adoc index 625670b3..7fdbbf29 100644 --- a/_pages/builder.adoc +++ b/_pages/builder.adoc @@ -25,7 +25,7 @@ Here're some of the features that make Metanorma a good match for document publishing workflows of a standards defining organization: [.feature-list] -* +++WYSIWYM+++ semantic authoring +* +++WYSIWYM+++ semantic authoring with syntax based on AsciiDoc. * Versionable document sources. diff --git a/_pages/developer.adoc b/_pages/developer.adoc new file mode 100644 index 00000000..d62bc140 --- /dev/null +++ b/_pages/developer.adoc @@ -0,0 +1,25 @@ +--- +layout: docs-base +html-class: docs-page +title: Developer Docs +redirect_from: + - /developer/ +--- + += Developer Documentation + +To build documents with Metanorma, you need to have the Metanorma +command-line toolchain installed. + +The toolchain consists of `metanorma-cli` Ruby gem and its dependencies. + +In general, these installation methods are recommended. + + + + +[[gems]] +== Installing gems separately + +See link:/software/metanorma-cli/[Metanorma CLI docs] +on how to install the Ruby gem on its own. diff --git a/_pages/docs.html b/_pages/docs.html new file mode 100644 index 00000000..30c48750 --- /dev/null +++ b/_pages/docs.html @@ -0,0 +1,49 @@ +--- +layout: docs-base +html-class: docs-page +title: Metanorma Documentation +--- + + + + + + + +
+

New User

+ New user image + + + + + + +
+ +
+

Advanced User

+ Advanced user image + + + + + + +
+ +
+

Developer

+ Developer + +
+ + + \ No newline at end of file diff --git a/_pages/flavors.adoc b/_pages/flavors.adoc index d6cd4be9..cc1eb9ae 100644 --- a/_pages/flavors.adoc +++ b/_pages/flavors.adoc @@ -51,6 +51,13 @@ NOTE: Some flavors are supported directly by user organizations. |+++BIPM+++ | link:/author/bipm/[Metanorma for BIPM] +|+++NIST+++ +| link:/author/nist/[Metanorma for NIST] (Private) + +|+++BSI+++ +| link:/author/bsi/[Metanorma for BSI] (Private) + + |=== [TIP] @@ -71,6 +78,9 @@ at the customization guidelines in link:/builder/[Metanorma builder's documentat |Chinese Standards | link:/author/gb/[Metanorma for GB] +|Japanese Industrial Standards +| link:/author/jis/[Metanorma for JIS] + |=== diff --git a/_pages/install.adoc b/_pages/install.adoc deleted file mode 100644 index b4fdafe2..00000000 --- a/_pages/install.adoc +++ /dev/null @@ -1,135 +0,0 @@ ---- -layout: docs-base -html-class: docs-page -title: Setting up Metanorma -redirect_from: - - /setup/ ---- -= Setting up Metanorma - -The Metanorma command-line toolchain can be installed with any of the following -installation methods suitable for your platform. - - -== Platform-specific installation - -Choose your platform: - -* link:/install/macos/[macOS] -* link:/install/windows/[Windows] -* link:/install/linux/[Linux] - - -== Platform-independent installation - -The following installation methods are intended for skilled Metanorma experts -who develop on Metanorma or require automated actions. - -* link:/install/docker/[Docker] -+ -[TIP] -.Installing via Docker -==== -Docker is a platform-independent container engine. The official -https://hub.docker.com/u/metanorma[Metanorma Docker containers on Docker Hub] -provide a simple and consistent to run Metanorma, especially on -continuous integration (CI) environments. -==== - -* link:/software/metanorma-cli/[Ruby gem] -+ -[TIP] -.Manual installation -==== -Assuming you know what you're doing, the -https://rubygems.org/gems/metanorma-cli[metanorma-cli] gem can be manually -installed. - -You will have to take care of dependencies: an appropriate Ruby version, -plus other software depending on the end documents you're building. - -Refer to link:/install/manual-installation[Metanorma CLI installation docs] -for details. -==== - - -== Continuous delivery environments - -Metanorma is often run on continuous integration (CI) and continuous deployment -(CD) environments. - -* link:/install/cicd[GitHub Actions and GitLab CI/CD] - - -== Running Metanorma - -Refer to the following documentation on how to run the `metanorma` command: - -* link:/install/man[Metanorma manual] for more details on its command options; and -* link:/install/usage[Using Metanorma] for instructions on how to use Metanorma. - - - -== Installing additional flavors - -The method to install additional flavors depends on how Metanorma was installed. - -* If Metanorma was installed through an installation package, such as from -SnapCraft (Linux), -Homebrew (macOS) or -Chocolatey (Windows), -these packages install the Metanorma single executable (built from `packed-mn`). -They do not support additional flavors. - -* If Metanorma was installed as a Ruby gem (from GitHub or -https://rubygems.org[RubyGems.org]), you can add the additional flavor gems -to your Ruby installation with one of these methods: - -** Directly install the flavor gem using `gem install metanorma-{flavor}` -+ -[TIP] -.Installing a flavor through the `gem install` command -==== -The following command installs the Ribose flavor. - -[source,sh] ----- -gem install metanorma-ribose ----- -==== - -** Install the flavor gem by specifying it in a `Gemfile`, then run the `bundle` -command -+ -[TIP] -.Installing a flavor through a Gemfile -==== -A `Gemfile` that adds the Ribose flavor: - -[source,ruby] ----- -source 'https://rubygems.org' - -gem 'metanorma-cli' -gem 'metanorma-ribose' ----- -==== - -* If you use Metanorma through Docker, using the official Metanorma Docker -images, additional flavors can be installed using `Gemfile`, and then running -the -https://github.com/metanorma/metanorma-build-scripts/blob/main/gemfile-to-bundle-add.sh[gemfile-to-bundle-add.sh] -script to add those to the running container. -+ -[TIP] -.Installing a flavor to a Metanorma Docker container -==== -The `Gemfile` specified above can be used in the Metanorma Docker images for -installing the additional `metanorma-ribose` flavor with the following command -run within the Docker container: - -[source,sh] ----- -curl -L https://raw.githubusercontent.com/metanorma/metanorma-build-scripts/main/gemfile-to-bundle-add.sh | bash ----- -==== diff --git a/_pages/install/cicd.adoc b/_pages/install/cicd.adoc index ca116460..5bc1833e 100644 --- a/_pages/install/cicd.adoc +++ b/_pages/install/cicd.adoc @@ -1,7 +1,7 @@ --- layout: docs-base html-class: docs-page -title: Getting started with Metanorma in CI/CD environments +title: Getting Started with Metanorma in CI/CD Environments redirect_from: - /setup/cicd --- @@ -10,34 +10,139 @@ Metanorma is often run on continuous integration (CI) and continuous deployment == Running on CI/CD platforms -We currently support the following CI/CD platforms: +Because metanorma provides a CLI toolchain it's straightforward to integrate it with any CI/CD platform. -* GitHub Actions -* GitLab CI +Because we use GitHub/GitLab for development integration with those CI platforms -=== Installation +=== GitHub Actions + +An example of the workflow for GitHub Actions may look like this: -Metanorma provides native packages installable on most major platforms and -these packages can be installed through a non-interactive console/terminal. -The full list is available link:/install/[here]. +[source,yml] +--- +name: generate -Metanorma also provides additional automated actions for the setup and running -of Metanorma on CI/CD testers. +on: + push: + branches: [ main ] + pull_request: + workflow_dispatch: -=== GitHub Actions +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + container: + image: metanorma/metanorma:latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Cache Metanorma assets + uses: actions-mn/cache@v1 -The following GitHub Actions can be used to simplify a Metanorma CI workflow: + - name: Metanorma generate site + uses: actions-mn/build-and-publish@main + with: + token: ${{ secrets.GITHUB_TOKEN }} + agree-to-terms: true -* Metanorma setup: https://github.com/marketplace/actions/setup-metanorma[`actions-mn/setup@v2`] + deploy: + if: ${{ github.ref == 'refs/heads/main' }} + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 +--- + +In the workflow above doesn't fit your needs you can create your own workflow based on a list of actions that metanorma provides: -* Metanorma CLI actions: https://github.com/actions-mn/cli[`actions-mn/cli/site-gen@main` and more] +* https://github.com/actions-mn/setup[`actions-mn/setup`] - used for installing `metanorma` CLI for Ubuntu, MacOS, or Windows +* https://github.com/actions-mn/cache[`actions-mn/cache`] - caches intermediate metanorma files (fonts, relaton data) to speedup compilation +* https://github.com/actions-mn/build-and-publish[`actions-mn/build-and-publish`] - do site generation and upload artifact for deployment -Please refer to our https://github.com/metanorma/mn-samples-iso[ISO samples repository] -for further reference. +The https://github.com/actions-mn/setup[`actions-mn/setup` GitHub Action] can be skipped if you run CI in a Docker environment and use the Metanorma Docker image. + +For complete workflow examples just check https://github.com/actions-mn/build-and-publish[README for `actions-mn/build-and-publish` action] === GitLab CI -Metanorma provides a sample `.gitlab-ci.yml` workflow file that demonstrates -how to use the Metanorma docker container in the environment. +An example of the workflow for GitHub Actions may look like this: + +[source,yml] +--- +image: + name: metanorma/metanorma + entrypoint: [ "" ] + +cache: + paths: + +stages: + - build + - deploy + + +build: + stage: build + script: + - curl -L --retry 3 https://raw.githubusercontent.com/metanorma/ci/main/gemfile-to-bundle-add.sh | bash + - bundle install + - metanorma site generate --output-dir public --agree-to-terms . + + artifacts: + paths: + - public + +pages: + dependencies: + - build + stage: deploy + script: + - | + curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" \ + "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=build" + artifacts: + paths: + - public + only: + - master + - main +--- + +If it is suitable for you you can reuse it with the following code (to minimize code duplication): + +[source,yml] +--- +include: +- remote: 'https://raw.githubusercontent.com/metanorma/ci/main/cimas-config/gitlab-ci/samples/docker.shared.yml' +--- + +=== Other CI providers + +Generally, the integration consists of 2 phases: + +* link:/install[installing metanorma toolchain] +* calling metanorma-cli by shell commands + +Most CI providers nowadays allow to run CI from a Docker execution environment: + +- https://docs.travis-ci.com/user/docker/[Travis CI] +- https://circleci.com/docs/using-docker/[CircleCI] +- https://www.jenkins.io/doc/book/pipeline/docker/[Jenkins] +- https://devcenter.bitrise.io/en/infrastructure/using-your-own-docker-image.html[Bitrise] -* https://github.com/metanorma/metanorma-build-scripts/blob/master/cimas-config/gh-actions/samples/.gitlab-ci.yml[Sample `.gitlab-ci.yml`] +Metanorma provides a wide set of docker images https://hub.docker.com/r/metanorma you can select what is suitable for you diff --git a/_pages/install/manual-installation.adoc b/_pages/install/manual-installation.adoc index 4f4e7d9b..289233cf 100644 --- a/_pages/install/manual-installation.adoc +++ b/_pages/install/manual-installation.adoc @@ -13,7 +13,7 @@ The `metanorma` command-line executable is installed by this Ruby gem. ==== Users of the Metanorma suite should install Metanorma according to the steps at the -https://www.metanorma.org/author/topics/install/[Metanorma installation guide]. +link:/author/topics/install/[Metanorma installation guide]. The instructions provided here are intended for Metanorma developers, since a number of third-party dependencies will also need to be installed manually. diff --git a/_pages/install/usage.adoc b/_pages/install/usage.adoc index 5f9c3274..83346193 100644 --- a/_pages/install/usage.adoc +++ b/_pages/install/usage.adoc @@ -275,6 +275,7 @@ repository. metanorma template-repo add my-templates https://github.com/example/my-templates ---- +[[metanorma-site]] == Generating a Metanorma site The `site` subcommand allows you to manage mini site generation using the CLI. diff --git a/_pages/installation.adoc b/_pages/installation.adoc new file mode 100644 index 00000000..e831c08d --- /dev/null +++ b/_pages/installation.adoc @@ -0,0 +1,299 @@ +--- +layout: docs-base +html-class: docs-page +title: Installation Guide +redirect_from: + - /setup/ +--- += Setting up Metanorma + +The Metanorma command-line toolchain can be installed with any of the following +installation methods suitable for your platform. + + +== Platform-specific installation + +Choose your platform: + +* link:/install/macos/[macOS] +* link:/install/windows/[Windows] +* link:/install/linux/[Linux] + + +== Platform-independent installation + +The following installation methods are intended for skilled Metanorma experts +who develop on Metanorma or require automated actions. + +* link:/install/docker/[Docker] ++ +[TIP] +.Installing via Docker +==== +Docker is a platform-independent container engine. The official +https://hub.docker.com/u/metanorma[Metanorma Docker containers on Docker Hub] +provide a simple and consistent to run Metanorma, especially on +continuous integration (CI) environments. +==== + +* link:/software/metanorma-cli/[Ruby gem] ++ +[TIP] +.Manual installation +==== +Assuming you know what you're doing, the +https://rubygems.org/gems/metanorma-cli[metanorma-cli] gem can be manually +installed. + +You will have to take care of dependencies: an appropriate Ruby version, +plus other software depending on the end documents you're building. + +Refer to link:/install/manual-installation[Metanorma CLI installation docs] +for details. +==== + + +== Continuous delivery environments + +Metanorma is often run on continuous integration (CI) and continuous deployment +(CD) environments. + +* link:/install/cicd[GitHub Actions and GitLab CI/CD] + + +== Running Metanorma + +Refer to the following documentation on how to run the `metanorma` command: + +* link:/install/man[Metanorma manual] for more details on its command options; and +* link:/install/usage[Using Metanorma] for instructions on how to use Metanorma. + + + +== Installing additional flavors + +The method to install additional flavors depends on how Metanorma was installed. + +* If Metanorma was installed through an installation package, such as from +SnapCraft (Linux), +Homebrew (macOS) or +Chocolatey (Windows), +these packages install the Metanorma single executable (built from `packed-mn`). +They do not support additional flavors. + +* If Metanorma was installed as a Ruby gem (from GitHub or +https://rubygems.org[RubyGems.org]), you can add the additional flavor gems +to your Ruby installation with one of these methods: + +** Directly install the flavor gem using `gem install metanorma-{flavor}` ++ +[TIP] +.Installing a flavor through the `gem install` command +==== +The following command installs the Ribose flavor. + +[source,sh] +---- +gem install metanorma-ribose +---- +==== + +** Install the flavor gem by specifying it in a `Gemfile`, then run the `bundle` +command ++ +[TIP] +.Installing a flavor through a Gemfile +==== +A `Gemfile` that adds the Ribose flavor: + +[source,ruby] +---- +source 'https://rubygems.org' + +gem 'metanorma-cli' +gem 'metanorma-ribose' +---- +==== + +* If you use Metanorma through Docker, using the official Metanorma Docker +images, additional flavors can be installed using `Gemfile`, and then running +the +https://github.com/metanorma/metanorma-build-scripts/blob/main/gemfile-to-bundle-add.sh[gemfile-to-bundle-add.sh] +script to add those to the running container. ++ +[TIP] +.Installing a flavor to a Metanorma Docker container +==== +The `Gemfile` specified above can be used in the Metanorma Docker images for +installing the additional `metanorma-ribose` flavor with the following command +run within the Docker container: + +[source,sh] +---- +curl -L https://raw.githubusercontent.com/metanorma/metanorma-build-scripts/main/gemfile-to-bundle-add.sh | bash +---- +==== +[[installation]] +== Installation + +[[macOS]] +=== Using https://brew.sh/[Homebrew] + +[source,sh] +---- +brew tap metanorma/metanorma +brew install metanorma +---- + +or + +[source,sh] +---- +brew install metanorma/metanorma/metanorma +---- + + +[[linux]] +== Linux + +[[snap]] +=== Using https://snapcraft.io[Snap] + +The easiest way is to install the https://snapcraft.io/metanorma[Metanorma Snap] +with a single command: + +[source,sh] +---- +sudo snap install metanorma +---- + +If `snapd` isn't available on your distribution, use the all-in-one install script +described below for various platforms. +You will need to have `curl` installed beforehand. + +TIP: For details, please see the https://github.com/metanorma/metanorma-linux-setup[metanorma-linux-setup] repository. + + +=== Install script for Ubuntu + +The `curl` command must be installed. + +[source,sh] +---- +sudo bash -c "curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/ubuntu.sh | bash" +curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/install-gems.sh | bash +---- + + +=== Install script for CentOS + +The `curl` command must be installed. + +[source,sh] +---- +sudo bash -c "curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/centos.sh | bash" +curl -L https://raw.githubusercontent.com/metanorma/metanorma-linux-setup/master/install-gems.sh | bash +---- + + +[[windows]] +== Windows + +[[chocolatey]] +=== Using https://chocolatey.org/[Chocolatey] + +To install `chocolatey` follow https://chocolatey.org/install[these instructions] + +Execute the following in your `cmd.exe` or `PowerShell` +to install the Metanorma Chocolatey package: + +[source,console] +---- +choco install metanorma -y +---- + +[TIP] +==== +For LaTeX processing, a UTF-8 compatible command line interface is necessary. +If you are using the Windows default command line interpreter `cmd.exe`, +please do run `chcp 65001` before using Metanorma. +==== + +[TIP] +==== +See +link:/blog/12-25-2018/metanorma-on-windows-via-chocolatey/[the blog post on Metanorma Chocolatey package] +for more background. +==== + + +[[docker-setup]] +== Docker setup + +This setup method works for all platforms that support the Docker container +framework. + +[TIP] +==== +This method is the recommended way of getting Metanorma installed. + +Possible reasons to _avoid_ this method: + +* Performance. Using Metanorma inside Docker container may be a bit slower. + +==== + +. Pull the container: ++ +[source,sh] +---- +docker pull metanorma/metanorma +---- + +. Specify the `:local-cache-only:` AsciiDoc attribute +in document header to speed up rendering (optional) + +To render the document into HTML, Word and XML, +execute from within the directory containing the Metanorma document +(replacing `{my-document-path}` with your actual document's filename): + +.Running the Metanorma container on macOS and Linux +[source,console] +-- +docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t {flavor} -x {output-formats} {my-document-path} +-- + +.Running the Metanorma container on Windows +[source,console] +-- +docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma compile -t {flavor} -x {output-formats} {my-document-path} +-- + +[TIP] +==== +See https://github.com/metanorma/metanorma-docker[metanorma-docker] for more information. +==== + + +[[gems]] +== Installing gems separately + +See link:/software/metanorma-cli/[Metanorma CLI docs] +on how to install the Ruby gem on its own. + +[[usecases]] +== Use-cases +Follow the links for your level of expertise with Metanorma: +[[new]] +== New User +If you are fairly new, follow these steps to get acquainted with our tool. + +[[experienced]] +== Experienced Users +If you have already used Metanorma, then probably you'd like to directly navigate to the Authoring Guide. Follow these steps. + +[[expert]] +== Expert +If you are well-versed with the tool, probably you belong to the developer level. Follow these steps to navigate to Developer Docs. + + diff --git a/_pages/reference_docs.adoc b/_pages/reference_docs.adoc new file mode 100644 index 00000000..cc00ede6 --- /dev/null +++ b/_pages/reference_docs.adoc @@ -0,0 +1,6 @@ +--- +title: Reference Documentation +description: References for standard Metanorma and all its flavors. +layout: reference-index +html-class: docs-page +--- \ No newline at end of file diff --git a/_pages/tutorials.html b/_pages/tutorials.html new file mode 100644 index 00000000..814aa292 --- /dev/null +++ b/_pages/tutorials.html @@ -0,0 +1,13 @@ +--- +title: Metanorma tutorials +description: A series of tutorials to get you familiar with the Metanorma toolchain. +layout: tutorial +#hero_include: index-page-hero.html +--- +

+ If you are completely unfamiliar with Metanorma, you've come to the right place. In this tutorial, you will learn how to create Metanorma documents, create outputs, and even learn the basics of troubleshooting. +

+ + +

Curriculum

+ \ No newline at end of file diff --git a/_posts/2018-11-29-writing-standards-with-metanorma.adoc b/_posts/2018-11-29-writing-standards-with-metanorma.adoc index 626f87d4..19976e95 100644 --- a/_posts/2018-11-29-writing-standards-with-metanorma.adoc +++ b/_posts/2018-11-29-writing-standards-with-metanorma.adoc @@ -26,8 +26,7 @@ So. *Why Metanorma*? == Standardization documents are complex If you're in the business of writing standards documents, you are in -the business of writing some of the most complicated documents there -are. +the business of writing some of the most complicated documents possible. * You are working on a document that is being *edited by committee*. diff --git a/_posts/2020-06-10-upgrading-metanorma-ietf-documents-to-v2.adoc b/_posts/2020-06-10-upgrading-metanorma-ietf-documents-to-v2.adoc index 48ec6f49..2a049722 100644 --- a/_posts/2020-06-10-upgrading-metanorma-ietf-documents-to-v2.adoc +++ b/_posts/2020-06-10-upgrading-metanorma-ietf-documents-to-v2.adoc @@ -86,7 +86,7 @@ In IETF RFCs and I-Ds, you just need this: === Custom reference notation -For custom bibliographic items, Metanorma now supports https://www.relaton.org/specs/asciibib/path/[AsciiBib], +For custom bibliographic items, Metanorma now supports https://www.relaton.org/asciibib/path/[AsciiBib], which is a way of specifying bibliographic data in an AsciiDoc-like syntax (with ASCII, of course). diff --git a/_posts/2021-03-26-metanorma-gsod-2021.adoc b/_posts/2021-03-26-metanorma-gsod-2021.adoc index 1dd1564b..c020cbc6 100644 --- a/_posts/2021-03-26-metanorma-gsod-2021.adoc +++ b/_posts/2021-03-26-metanorma-gsod-2021.adoc @@ -23,7 +23,7 @@ image::/assets/blog/2021-03-26-gsod-2021.png[Google Season of Docs 2021 logo] == About Metanorma -https://www.metanorma.org[Metanorma] is an open-source, freely-licensed authoring framework for writing and publishing machine-readable, semantic standards. Semantic standards preserve the intent of the standards to be understood by the standards readers without potential corruption in meaning. +link:/[Metanorma] is an open-source, freely-licensed authoring framework for writing and publishing machine-readable, semantic standards. Semantic standards preserve the intent of the standards to be understood by the standards readers without potential corruption in meaning. Metanorma was first launched in 2017 and is now used by standards authors worldwide among leading standards development organizations (SDOs), including https://www.iso.org[ISO], https://www.iec.ch[IEC], https://www.itu.int[ITU], https://www.ietf.org[IETF], and industry standards bodies such as https://www.ogc.org[OGC] and https://www.calconnect.org[CalConnect], as well as governmental organizations like https://www.nist.gov[NIST] and the https://www.bsigroup.com[BSI (British Standards Institution)]. These authors use Metanorma to create standards across broad swathes of industries: from smart manufacturing to geographic information, internet technology to health and safety. @@ -50,11 +50,11 @@ https://www.iec.ch/dyn/www/f?p=103:85:15986998532293::::FSP_ORG_ID,FSP_LANG_ID:2 === Current status -The Metanorma website hosts numerous https://www.metanorma.org/blog/[blog posts], guides, specifications, and other reference documents. These include documentation on its information models, setup and usage guides, as well as customization and programming references. +The Metanorma website hosts numerous link:/blog/[blog posts], guides, specifications, and other reference documents. These include documentation on its information models, setup and usage guides, as well as customization and programming references. For every SDO flavor, the following documentation is provided: -* A reference guide is provided detailing the use of specific functions and metadata information necessary for documents. For example, the Metanorma ITU guide is found here: https://www.metanorma.org/author/itu/ref/document-attributes/. +* A reference guide is provided detailing the use of specific functions and metadata information necessary for documents. For example, the Metanorma ITU guide is found here: link:/author/itu/ref/document-attributes/. * A sample document repository is provided for authors to quickly get started with compilable examples of the flavor's document types. Each sample document comes from a real example authored in Metanorma with full annotations in order to make it as realistic as possible with the necessary details for authoring education. diff --git a/_posts/2021-06-30-halfway-into-gsod.adoc b/_posts/2021-06-30-halfway-into-gsod.adoc index 24769f82..25bdf165 100644 --- a/_posts/2021-06-30-halfway-into-gsod.adoc +++ b/_posts/2021-06-30-halfway-into-gsod.adoc @@ -62,7 +62,7 @@ Since we now know what our users expect to find, we looked at selected content s * Shortness * Stimulating additions -We've clarified the deficits in the “Further remarks” section and gave recommendations on how to improve the content. We have also looked at the https://readable.com/blog/the-flesch-reading-ease-and-flesch-kincaid-grade-level/[Flesch-Kincaid] readability index to check if there's very complicated-to-read content. Luckily most pages were understandable by 9th-10th graders, which means that also people with English as their second language will understand the information easily. +We've clarified the deficits in the "Further remarks" section and gave recommendations on how to improve the content. We have also looked at the https://readable.com/blog/the-flesch-reading-ease-and-flesch-kincaid-grade-level/[Flesch-Kincaid] readability index to check if there's very complicated-to-read content. Luckily most pages were understandable by 9th-10th graders, which means that also people with English as their second language will understand the information easily. .A short peek into our analysis. image::/assets/blog/2021-06-30-quality.png[A short peek into our analysis.] diff --git a/_posts/2022-03-13-iso-house-style.adoc b/_posts/2022-03-13-iso-house-style.adoc index 279fe1de..c7050dc9 100644 --- a/_posts/2022-03-13-iso-house-style.adoc +++ b/_posts/2022-03-13-iso-house-style.adoc @@ -190,7 +190,7 @@ https://www.iso.org/ISO-house-style.html#iso-hs-s-formatting-r-vocabulary[Vocabu ____ A vocabulary is the only ISO document that can have terminological entries in clauses other than Clause 3. If terminological entries are given in other -clauses, use a clause title starting “Terms related to”. Terminological entries +clauses, use a clause title starting "Terms related to". Terminological entries are never included in annexes. ____ @@ -204,8 +204,8 @@ Metanorma supports the designed behavior: [quote,ISO House Style] ____ -Do not include the first line of the fixed text for Clause 3, i.e. “For the -purposes of this document, the following terms and definitions apply.” This is +Do not include the first line of the fixed text for Clause 3, i.e. "For the +purposes of this document, the following terms and definitions apply." This is not needed in a vocabulary document because the terminological entries apply to all the documents of the committee. ____ @@ -239,12 +239,12 @@ https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-p-and[And/Or]: [quote,ISO House Style] ____ -The phrase “and/or” is often used in English to express “either or both” of two +The phrase "and/or" is often used in English to express "either or both" of two options. The meaning can be ambiguous, especially in translation to other -languages where the “/” is not a recognized punctuation mark. +languages where the "/" is not a recognized punctuation mark. -Avoid using “and/or” in a document to avoid confusion and misapplication. Use -the construction “either x or y, or both” instead. +Avoid using "and/or" in a document to avoid confusion and misapplication. Use +the construction "either x or y, or both" instead. ____ The conjunction phrase _and/or_ is to be avoided. Metanorma issues a warning if @@ -254,7 +254,7 @@ https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-p-andor[And or &]: [quote,ISO House Style] ____ -ISO documents do not use the ampersand (&) in ordinary text. Use the word “and” instead. +ISO documents do not use the ampersand (&) in ordinary text. Use the word "and" instead. ____ The ampersand is to be avoided in ordinary text. Metanorma warns on encountering diff --git a/_posts/2022-07-27-reviewer-annotations-in-pdf.adoc b/_posts/2022-07-27-reviewer-annotations-in-pdf.adoc new file mode 100644 index 00000000..81eb62f4 --- /dev/null +++ b/_posts/2022-07-27-reviewer-annotations-in-pdf.adoc @@ -0,0 +1,94 @@ +--- +layout: post +title: "Reviewer annotations are available now in Metanorma PDFs" +date: 2022-07-27 +categories: documentation +authors: + - + name: Ronald Tse + email: ronald.tse@ribose.com + social_links: + - https://github.com/ronaldtse + - + name: Alexander Dyuzhev + email: dyuzhev@gmail.com + social_links: + - https://www.linkedin.com/in/alexander-dyuzhev/ + - https://github.com/Intelligent2013/ + +excerpt: >- + Metanorma-generated PDFs contain now reviewer notes and comments annotated + by Metanorma reviewer comments AsciiDoc markup feature. +--- + +== Introduction + +As you may know you can annotate a Metanorma AsciiDoc document with comments and +'TODO's text: link:/author/topics/document-format/reviewer-notes/[Reviewer notes and comments] +Until recently, the Metanorma-generated DOC and HTML only contained reviewer notes. +Now reviewer notes available in the generated PDFs. + + +== How Metanorma publishes reviewer notes in PDF + +Let's take an example from https://github.com/metanorma/mn-samples-iso/blob/main/sources/international-standard/body/body-en.adoc +``` +[reviewer=ISO,date=2017-01-01,from=foreword,to=foreword] +**** +A Foreword shall appear in each document. The generic text is shown here. It does not contain requirements, recommendations or permissions. + +For further information on the Foreword, see *ISO/IEC Directives, Part 2, 2016, Clause 12.* +**** +``` + +It's standalone reviewer note that doesn't relate to concrete text and shows at the end of the section. + +The following example demonstrates how this reviewer note renders in a generated PDF document: +* small orange icon with a tool-tip +* comment's text in the Acrobat Reader Comment tool panel + +.Reviewer note in a generated PDF document +image::/assets/blog/2022-07-27_1.png[Reviewer note in a generated PDF document] + + +In the second example we add reviewer note for the concrete word in the text: +``` +This second edition cancels and replaces the [[start_review1]]second[[end_review1]] edition (ISO {docnumber}-{partnumber}:2009), which has been technically revised. +... + +[reviewer=ISO,date=2022-07-01,from=start_review1,to=end_review1] +**** +Instead of _second_ should be _first_. +**** +``` + +The following example demonstrates how this 'in-lined' reviewer note renders in a generated PDF document: +* small orange icon with a tool-tip +* highlighted text +* comment's text in the Acrobat Reader Comment tool panel + +.In-lined reviewer note in a generated PDF document +image::/assets/blog/2022-07-27_2.png[In-lined reviewer note in a generated PDF document] + + +== How reviewer notes renders in the popular PDF readers + +The PDF readers have different support for the reviewer notes ('comments' in terms of PDF) and rich text (bold, italic) in them. + +.Compatibility of PDF comments across popular PDF readers +|=== +| PDF viewer application | Comments support | Rich text support + +| Adobe Reader | ✅ | ✅ +| Foxit PDF Reader | ✅ | doesn't display rich text from the generated PDF, but text can be formatted as rich text +| Preview (macOS) | ✅ | ❌, text displays as plain text only +| Skim (macOS) | ✅ | ❌, text displays as plain text only +| Firefox (browser) | ✅ | doesn't display bolded text, only italic +| Safari (browser) | shows only orange icon | doesn't display text at all +| Microsoft Word | ❌ | ❌ +|=== + + +== References + +* link:/author/topics/document-format/reviewer-notes/[Reviewer notes and comments] diff --git a/_posts/2022-08-22-annotations-available-in-all-ouputs.adoc b/_posts/2022-08-22-annotations-available-in-all-ouputs.adoc index c130be38..377244d6 100644 --- a/_posts/2022-08-22-annotations-available-in-all-ouputs.adoc +++ b/_posts/2022-08-22-annotations-available-in-all-ouputs.adoc @@ -364,4 +364,4 @@ matrix in <> for the intended audience. == Bibliography -* https://www.metanorma.org/author/topics/document-format/annotations/[Annotations in Metanorma] +* link:/author/topics/document-format/annotations/[Annotations in Metanorma] diff --git a/_posts/2022-11-17-xmlsts-to-metanorma.adoc b/_posts/2022-11-17-xmlsts-to-metanorma.adoc index c288a0db..305c7f80 100644 --- a/_posts/2022-11-17-xmlsts-to-metanorma.adoc +++ b/_posts/2022-11-17-xmlsts-to-metanorma.adoc @@ -128,8 +128,7 @@ the previous sections, it is quite likely that some adjustments will need to be made to get a properly encoded Metanorma AsciiDoc. In other words, we need to validate that the Metanorma encoding rules are correctly applied. -https://www.metanorma.org/author/topics/document-format/[Metanorma -documentation] +link:/author/topics/document-format/[Metanorma documentation] will be our best ally in this chore. This should be a quick validation though, given that the _mnconvert_ tool does the majority of the work. However, the complexity of the validation depends on the source XML file itself. @@ -208,7 +207,7 @@ blocks are encoded properly with the `[source]` attribute. It is preferable to specify which programming language is used in the code block. Sometimes, there is a need to introduce markup into the source code. If any -term is boldfaced, italicized, or underlined, it should be surrounded by +term is boldfaced, italicized, or underlined, it should be surrounded by delimiters `{{{...}}}` for enabling markup; you also have the option of https://docs.asciidoctor.org/asciidoc/latest/subs/apply-subs-to-blocks/#the-subs-attribute[the subs attribute] configured as `subs="verbatim,quotes"`, to enable rich text inside code. diff --git a/_posts/2023-05-11-updated-iso-house-style.adoc b/_posts/2023-05-11-updated-iso-house-style.adoc new file mode 100644 index 00000000..80ffd0ed --- /dev/null +++ b/_posts/2023-05-11-updated-iso-house-style.adoc @@ -0,0 +1,33 @@ +--- +layout: post +title: 'Validating against ISO House Style' +date: 2023-05-11 +categories: documentation +authors: + - + name: Nick Nicholas + email: nick.nicholas@ribose.com + social_links: + - https://github.com/opoudjis + +excerpt: >- + Metanorma validation against the ISO House Style for ISO deliverables + has been updated to the 2023 version of the style guide. +--- + +In link:/blog/2022-03-13-iso-house-style.adoc/[Validating against ISO House Style], +we noted that Metanorma-ISO now validates ISO documents against the ISO House Style, +issuing various warnings for wording and punctuation to ensure compliance against +that style guide. + +The implementation of ISO House Style validation has now been updated to the 2023 +version of the style guide. The following rules have been added: + +* https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-need[Need to], +https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-might[might & could]: +Warn of ambiguous provision wording. +* https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-quantity[Quantities and units]: +Warn of more than one level of nesting of subscripts. +* https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-r-ref_unnumbered[Cross-references to an unnumbered document]: +Superscript cross-references must follow punctuation. + diff --git a/assets/author/advanced_user.svg b/assets/author/advanced_user.svg new file mode 100644 index 00000000..155f430c --- /dev/null +++ b/assets/author/advanced_user.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/author/beginner.svg b/assets/author/beginner.svg new file mode 100644 index 00000000..ed4947ad --- /dev/null +++ b/assets/author/beginner.svg @@ -0,0 +1 @@ +StartUP 1 \ No newline at end of file diff --git a/assets/author/concepts/Metanorma_WSYIWYM.png b/assets/author/concepts/Metanorma_WSYIWYM.png new file mode 100644 index 00000000..5749c265 Binary files /dev/null and b/assets/author/concepts/Metanorma_WSYIWYM.png differ diff --git a/assets/author/concepts/Metanorma_Workflow.png b/assets/author/concepts/Metanorma_Workflow.png new file mode 100644 index 00000000..33fdf017 Binary files /dev/null and b/assets/author/concepts/Metanorma_Workflow.png differ diff --git a/assets/author/concepts/Word_WSYIWYG.png b/assets/author/concepts/Word_WSYIWYG.png new file mode 100644 index 00000000..2c2a63ce Binary files /dev/null and b/assets/author/concepts/Word_WSYIWYG.png differ diff --git a/assets/author/concepts/complexity_pyramid.png b/assets/author/concepts/complexity_pyramid.png new file mode 100644 index 00000000..119a2f75 Binary files /dev/null and b/assets/author/concepts/complexity_pyramid.png differ diff --git a/assets/author/developer.svg b/assets/author/developer.svg new file mode 100644 index 00000000..ae59d509 --- /dev/null +++ b/assets/author/developer.svg @@ -0,0 +1 @@ +23 \ No newline at end of file diff --git a/assets/author/topics/document-format/text/fig-smallcaps.png b/assets/author/topics/inline_formatting/fig-smallcaps.png similarity index 100% rename from assets/author/topics/document-format/text/fig-smallcaps.png rename to assets/author/topics/inline_formatting/fig-smallcaps.png diff --git a/assets/author/topics/document-format/text/fig-strikethrough.png b/assets/author/topics/inline_formatting/fig-strikethrough.png similarity index 100% rename from assets/author/topics/document-format/text/fig-strikethrough.png rename to assets/author/topics/inline_formatting/fig-strikethrough.png diff --git a/assets/author/topics/document-format/text/fig-underline.png b/assets/author/topics/inline_formatting/fig-underline.png similarity index 100% rename from assets/author/topics/document-format/text/fig-underline.png rename to assets/author/topics/inline_formatting/fig-underline.png diff --git a/assets/blog/2022-07-27_1.png b/assets/blog/2022-07-27_1.png new file mode 100644 index 00000000..44c07086 Binary files /dev/null and b/assets/blog/2022-07-27_1.png differ diff --git a/assets/blog/2022-07-27_2.png b/assets/blog/2022-07-27_2.png new file mode 100644 index 00000000..1b839399 Binary files /dev/null and b/assets/blog/2022-07-27_2.png differ diff --git a/author/bipm/ref/document-attributes.adoc b/author/bipm/ref/document-attributes.adoc index a10acee2..665d2262 100644 --- a/author/bipm/ref/document-attributes.adoc +++ b/author/bipm/ref/document-attributes.adoc @@ -36,6 +36,7 @@ the document was issued. * `strategy` * `cipm-mra` * `resolution` +* `policy` (for JCTLM) [added in https://github.com/metanorma/metanorma-bipm/releases/tag/v2.4.3] -- `:status:`:: The document status. Permitted types are: @@ -49,8 +50,8 @@ the document was issued. `:language:`:: *Mandatory.* The language of the document (`en` or `fr`) -`:title-en:`:: *Mandatory.* The title of the document in English. -`:title-fr:`:: *Mandatory.* The title of the document in French. +`:title-en:`:: *Mandatory.* The title of the document in English. For JCGM documents treated as equivalent to `title-main-en` in ISO. +`:title-fr:`:: *Mandatory.* The title of the document in French. For JCGM documents treated as equivalent to `title-main-fr` in ISO. `:title-cover-en:`:: The title of the front cover of the document in English (where different from the title proper). `:title-cover-fr:`:: The title of the front cover of the document in French (where different from the title proper). diff --git a/author/bsi.adoc b/author/bsi.adoc new file mode 100644 index 00000000..a3fefa69 --- /dev/null +++ b/author/bsi.adoc @@ -0,0 +1,7 @@ +--- +layout: bsi-flavor +title: Write BSI documents with Metanorma +--- +:page-liquid: + +{% include flavor-quickstart-steps.adoc flavor=layout.bsi_flavor %} diff --git a/author/bsi/ref.adoc b/author/bsi/ref.adoc new file mode 100644 index 00000000..fbe5c9e3 --- /dev/null +++ b/author/bsi/ref.adoc @@ -0,0 +1,4 @@ +--- +layout: bsi-flavor +title: Metanorma-BSI reference guides +--- diff --git a/author/bsi/ref/document-attributes.adoc b/author/bsi/ref/document-attributes.adoc new file mode 100644 index 00000000..8669a9da --- /dev/null +++ b/author/bsi/ref/document-attributes.adoc @@ -0,0 +1,200 @@ +--- +layout: bsi-flavor +--- + += Metanorma BSI document attributes + +[[note_general_doc_ref_doc_attrib_ieee]] +[NOTE] +==== +Document attributes listed below are unique to the processing of BSI documents +in Metanorma. + +For _common document attributes_, see link:/author/ref/document-attributes/[Document attributes reference] in general Metanorma author's documentation. That page describes attributes that apply to all Metanorma flavors, not just IEEE SA. + +For an _introduction to Metanorma AsciiDoc document attributes_ and how Metanorma uses them, see link:/author/topics/document-format/meta-attributes/[the corresponding topic]. +==== + +== Document types + +The following document types are recognised in the `:doctype:` document attribute: + +BSI document types:: ++ +-- +* british-standard +* draft-for-development +* published-document +* privately-subscribed-standard +* publicly-available-specification +* flex-standard +-- + +Adoptable types, ISO :: ++ +-- +* international-standard +* technical-specification +* technical-report +* guide +* publicly-available-specification +* international-workshop-agreement +-- + + +Adoptable types, IEC :: ++ +-- +* international-standard +* technical-specification +* technical-report +* industry-technical-agreement +-- + +Adoptable types, CEN and CENELEC :: ++ +-- +* standard +* technical-specification +* technical-report +* guide +* european-workshop-agreement +-- + +The following document types are recognised in the `:docsubtype:` document attribute: + +* specification +* method-of-test +* method-of-specifying +* vocabulary +* code-of-practice + +== Document numbers + +In the case of native BS standards, the identifier is compiled from a combination of the `doctype`, +`docnumber`, and `copyright-year` document attributes, with a numeric `docnumber` value. So + +[source,asciidoctor] +---- +:docnumber: 1000 +:doctype: publicly-available-specification +:copyright-year: 2021 +---- + +generates the document identifier "PAS 1000:2021". + +In the case of document adoptions, the `docidentifier` attribute should be used (to which `BS` will be prefixed), +instead of assembling an identifier out of components, so that the source document identifier can be built up accurately. +Part numbers of the original document should also be included in the `docidentifier` attribute, +instead of being named with the `partnumber` attribute. So + +[source,asciidoctor] +---- +:docidentifier: ISO/TR 123-2:1985 +:doctype: technical-report +---- + +generates the document identifier "BS ISO/TR 123-2:1985". + +Note that the `:copyright-year:` attribute is added to the identifier of a native BSI document, +but not to that of an adopted document. So a 2022 adoption of ISO 123:1985 will still have the identifer +"BS ISO 123:1985". + +== Related BSI Standards + +The frontispiece of BSI Standards includes text like the following: + +____ +The following BSI references relate to the work on this document: + +Committee reference DEF/1 + +Draft for comment 20/30387670 DC +____ + +This text is created by adding the BSI list of documents that the document relates to +as a semicolon-delimited list of references, using `:bsi-related:`: + +[source,asciidoctor] +---- +:bsi-related: Committee reference DEF/1;Draft for comment 20/30387670 DC +---- + +The introductory phrase is added automatically. + +== Adoption of standard + +An adopted external standard is defined as `:adopted-from:`: + +[source,asciidoctor] +---- +:docidentifier: NA to BS EN 1991-1-2 +:adopted-from: EN 1991-1-2 +---- + + +[source,asciidoctor] +---- +:docidentifier: BS ISO 639-2 +:adopted-from: ISO 639-2 +---- + +The identifier for such adoptions is generated based on the `:adopted-from:` value, if +`:docidentifier:` is not supplied. + +== Expert Commentaries + +Expert commentaries are of type `:doctype: expert-commentary`, and are commentaries of another +document; the related document is indicated with `:annotation-of:`. + +The author of the commentary is indicated as the author of the document, including credentials +(indicated with `:contributor-credentials:`) and their position (`:contributor-position:`) and +possibly organisational affiliation (`:affiliation:`). The position can be discursive. + +[source,asciidoctor] +---- +:docidentifier: BS ISO 639-2 +:annotation-of: ISO 639-2 +:fullname: Eamonn Hoxey +:contributor-credentials: PhD, F.R.Pharm.S. +:contributor-position: Vice President, Medical Devices Quality & Compliance -- Strategic programmes, Johnson & Johnson Medical Ltd, Former Chair ISO TC 210, Quality management and related general aspects for medical devices, and Principal UK Expert to ISO TC 210 WG 1, Quality Management Systems. +:role: author +---- + +== Visual appearance + +`:coverpage-image:`:: Comma-delimited list of image locations, for images to be included on the PDF cover page. All image locations are relative to the source document. +`:innercoverpage-image:`:: Same, for images to be included on the PDF inside cover page. +`:tocside-image:`:: Same, for images to be included on the PDF Table of Contents side page. +`:backpage-image:`:: Same, for images to be included on the PDF back page. + +`:presentation-metadata-color-cover-background:`:: Background colour on PDF front cover (BSI Flex and PAS only), as #HEX. +`:presentation-metadata-color-cover-title:`:: Title colour on PDF front cover (PAS only), as #HEX. +`:presentation-metadata-color-secondary-shade-1:`:: Colour on PDF text accents (headings, titles and odd table header rows, BSI Flex and PAS only), as #HEX. +`:presentation-metadata-color-secondary-shade-2:`:: Colour (lighter accents) on PDF even (odd for preface) table header rows (BSI Flex and PAS only), as #HEX. +`:presentation-metadata-color-secondary-shade-3:`:: Colour (even lighter accents) on PDF odd (even for preface) table body rows (BSI Flex and PAS only), as #HEX. +`:presentation-metadata-color-secondary-shade-4:`:: Colour (much lighter accent) for background on PDF preface and even table body rows (BSI Flex and PAS only), as #HEX. +`:presentation-metadata-color-list-label:`:: List item bullet and label colour (BSI Flex and PAS only), as #HEX. +`:presentation-metadata-color-clause-union-background:`:: Background colour on clauses under floating titles (BSI Flex and PAS only), as #HEX +`:presentation-metadata-color-backpage-background:`:: Background colour on PDF back cover (BSI Flex and PAS only), as #HEX. + +`:presentation-metadata-layout-columns:`:: Alternate between one-column and two-column output; default is `1`. `2` is expected for PAS documents authored before 2023. + +`:toclevels:`:: +Number of table of contents levels to render. Accepts an integer value. (default: `1` for BSI). +Can be overridden with output-specific options (`htmltoclevels`, `doctoclevels`). + +`:htmltoclevels:`:: +Number of table of contents levels to render in HTML output; used to override +`:toclevels:` for HTML output. Accepts an integer value. (default: `1` for BSI). + +`:doctoclevels:`:: +Number of table of contents levels to render in Microsoft Word "DOC" output; +used to override `:toclevels:` for Word DOC output. Accepts an integer value. +(default: `1` for BSI). + +`:document-scheme:`:: +Picks the form of document presentation to be used. If `with-publication-information` is given, +the document history of the document is given in the old style, with full publication history +(enumerating all editions), and with four columns for amendments (date issued, date effective, +amendment designation, description). If it is not, the document history is given in the new style: +no publication history, and two columns for amendments (date issued, description). The +scheme is ignored in Flex and PAS, which use full document history, but two columns for amendments. diff --git a/author/bsi/topics.adoc b/author/bsi/topics.adoc new file mode 100644 index 00000000..31c68b88 --- /dev/null +++ b/author/bsi/topics.adoc @@ -0,0 +1,4 @@ +--- +layout: bsi-flavor +title: Using Metanorma-BSI +--- diff --git a/author/bsi/topics/bsiflex.png b/author/bsi/topics/bsiflex.png new file mode 100644 index 00000000..dd5fc04a Binary files /dev/null and b/author/bsi/topics/bsiflex.png differ diff --git a/author/bsi/topics/bsipas.png b/author/bsi/topics/bsipas.png new file mode 100644 index 00000000..60810bab Binary files /dev/null and b/author/bsi/topics/bsipas.png differ diff --git a/author/bsi/topics/formats.adoc b/author/bsi/topics/formats.adoc new file mode 100644 index 00000000..516d05cc --- /dev/null +++ b/author/bsi/topics/formats.adoc @@ -0,0 +1,16 @@ +--- +layout: bsi-flavor +title: Metanorma for BSI output formats +--- + +== Metanorma for BSI output formats + +=== General + +Metanorma for BSI supports the generation of the following formats. + +`html`:: HTML output +`pdf`:: PDF output +`sts` :: ISOSTS XML format: refer to link:/author/iso/topics/formats[Metanorma for ISO output formats] + +To obtain ISOSTS XML output, you will need to explicitly specify it as an output: `metanorma compile document.adoc -x sts`. diff --git a/author/bsi/topics/markup.adoc b/author/bsi/topics/markup.adoc new file mode 100644 index 00000000..87d5e4d2 --- /dev/null +++ b/author/bsi/topics/markup.adoc @@ -0,0 +1,825 @@ +--- +layout: bsi-flavor +title: Metanorma for BSI markup +--- + +== Visual Presentation + +=== Cover page images + +Any images to be included in the cover page are to be given under the +document attribute `coverpage-image`, as a comma-delimited list: + +[source,asciidoctor] +---- +:coverpage-image: images/image1.gif,images/image2.gif +---- + +The inner cover images, Table of Contents side images, and back page images are treated in the same way, +with the respective atttributes `innercoverpage-image`, `tocside-image`, and `backpage-image`. + +Note that even if an `:imagesdir:` directory is specified, the image locations should be given +relative to the source document, for consistency with other attributes. + +When preparing cover images for rendering in BSI PDF, bear in mind the following: + +For BSI Flex: + +* the cover page size is 210×297mm, +* the recommended main image (picture) size is 210×147mm, +* the recommended top margin for the main image is 85mm (the cover page title(s) renders in the area before the image, and the document identifier renders in the ares after the image), +* the document identifier renders on-the-fly in the area after the image, with top-margin 236mm, +* any sponsor logo(s) at the left bottom should be provided in addition to the cover page image, +* the BSI logo at the right bottom renders on-the-fly, and there no need to include it as a cover page image. + +image::bsiflex.png[] + +For BSI PAS: + +* the front and back cover page size is 210×297mm, +* the document identifier and title(s) displays in color (as determined by the document attribute `:presentation-metadata-color-cover-title:`, default value is `#ffffff1), in the block (shown in yellow box below) with margins at page sizes: left margin 15mm, top margin 12.5mm, right margin 25mm. Therefore the background of the cover page image should allow those margins to be correctly visualised, +* any sponsor logo(s) at the left bottom should be provided in addition to the cover page image, +* the BSI logo at the right bottom renders on-the-fly, and there no need to include it as a cover page image. + +image::bsipas.png[] + +=== Collection cover page style + +In Metanorma Collections, the Collection cover page style is determined by the first document type in the collection. +The style for the collection cover page can be chosen by the attribute `coverpage-style:` in the collection manifest file: + +``` +directives: + - coverpage-style: ... +``` + +Currently supported values for `coverpage-style:`: `BSI` (or `BS`) and `PAS`. + +NOTE: 'PAS' style cover page is using for BSI Flex collection also. + +=== Columns + +By default, BSI documents are output with one column per page. For PAS documents authored before 2023, +output is expected to be two columns per page for the document proper; this is indicated by the document attribute +`:presentation-metadata-layout-columns: 2`. + +=== Font +BSI documents require the BSI Gesta font to be installed in order to render HTML and PDF +outputs correctly. The BSI Gesta font cannot be freely distributed, but can be made available +for use under Metanorma by requesting access to the repository https://github.com/metanorma/fontist-formulas-private + +Once you have access to that repository, execute the following commands to make the BSI Gesta font +available to Metanorma: + +[source,console] +---- +fontist repo setup metanorma https://github.com/metanorma/fontist-formulas-private +fontist repo update metanorma +fontist install "BSI Gesta" +---- + +=== Boilerplate text + +By default, coverpage and frontispiece text is automatically added by Metanorma. That includes copyright information, +draft notices, and contact information about the BSI. + +BSI Flex standards include inside front cover material specific to that type of standard, as required by the current Flex style guide: + +____ +e) a description of the programme, if applicable, worded as follows: + This BSI Flex is part of a wider programme of work around XXXX. For more information, go + to: https://www.bsigroup.com/XXX + +f) a link to the project website, worded as follows; + Information on the development of this BSI Flex can be found at: + https://www.bsigroup.com/XXX + +g) a statement about BSI Flex standards, worded as follows: + BSI Flex standards provide a new, flexible way to develop consensus-based good practice + that dynamically adapts to keep pace with fast-changing markets. For more information, go to: + https://www.bsigroup.com/en-GB/our-services/standards-services/flex/ +____ + +Because there is variability in this information, including whether e) and f) are distinct paragraphs, +the text for e) and f) should be entered as a preface clause of type "flex-coverpage"; any title provided will +be ignored. For example: + +[source,asciidoctor] +---- +[.preface,type="flex-coverpage"] +== Flex cover page + +This BSI Flex is part of a wider programme of work around CAVs. For more information, go +to: https://www.bsigroup.com/en-GB/CAV/ +---- + +The text for g) is the same for all BSI Flex standards, and is supplied automatically after the information +in e) and f). + +BSI Flex and PAS documents also include a publication history (labelled "Release history" in BSI Flex); +it appears after g) in BSI Flex, and in the bottom of the Publication and Copyright Information. +The publication history is enterd with a preface clause of type "publication-history"; any title +supplied is overwritten with the title specific to the document type. For example: + +[source,asciidoctor] +---- +[.preface,type="publication-history"] +== Release history + +First published November 2001 + +Second edition January 2006 +---- + +== Clauses + +=== Adoption forewords + +When BSI adopts a standard from another SDO, it may insert its own foreword before the foreword +of the original document. If the standard has been adopted via a regional SDO such as CEN, +that regional SDO may have already added its own foreword. + +In order to ensure that the national and regional forewords are shown before the original foreword, +they need to be specified as prefatory clauses, of type "national-foreword" and "regional-foreword". +The `== Foreword` markup is retained for the source document. (Marking it as `.preface` is optional, +as Metanorma already recognises `== Foreword` as a prefatory clause. Marking the National and Regional +forewords as `.preface` is mandatory.) + +[source,asciidoctor] +---- +[.preface,type=national-foreword] +== National foreword + +BSI has adopted... + +[.preface,type=regional-foreword] +== Regional foreword + +CEN has adopted... + +[.preface] +== Foreword +The ISO standard... +---- + +=== Document history + +Semantic markup of document history can be added to the document, +link:/author/topics/document-format/meta-attributes#doc-history-misc-container[using Metanorma extension] +and Relaton YAML [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.0]. +Document history is realised as one or two subclauses of the copyright information, given in the +initial boilerplate text of the document. + +There are three forms of document history renderings: + +* If `:document-scheme: with-publication-information` is given, +the document history of the document is given in the old style, with full publication history +(enumerating all editions), and with four columns for amendments (date issued, date effective, +amendment designation, description). +* If `:document-scheme:` is not specified, the document history is given in the new style: +no publication history, and two columns for amendments (date issued, description). +* The document scheme is ignored in Flex and PAS, which use full document history, but two columns for amendments. +(The publication history is titled "Release history" in Flex.) + +The full document history tracks changes in document identifier; for that reason, BSI document histories +should specify the preferred identifier. + +In order to differentiate editions in the document history from versions in the amendment history, +the dates for the latter should be given with `type: updated`, whereas the former should be given with `type: published`. + +The following is an illustration of semantic document history markup for BSI: + +[source, asciidoctor] +-- +[.preface] +== Misc-container + +=== document history + +[source,yaml] +---- +- date: + - type: published + value: 1976-03 + docid: + - type: BSI + id: BS 5500 + edition: 1 +- date: + - type: published + value: 1982-01 + docid: + - type: BSI + id: BS 5500 + edition: 2 +- date: + - type: published + value: 1985-01 + docid: + - type: BSI + id: BS 5500 + edition: 3 +- date: + - type: published + value: 1988-01 + docid: + - type: BSI + id: BS 5500 + edition: 4 +- date: + - type: published + value: 1991-01 + docid: + - type: BSI + id: BS 5500 + edition: 5 +- date: + - type: published + value: 1994-01 + docid: + - type: BSI + id: BS 5500 + edition: 6 +- date: + - type: published + value: 1997-01 + docid: + - type: BSI + id: BS 5500 + edition: 7 +- date: + - type: published + value: 2000-01 + docid: + - type: BSI + id: PD 5500 + edition: 1 +- date: + - type: published + value: 2003-01 + docid: + - type: BSI + id: PD 5500 + edition: 2 +- date: + - type: published + value: 2006-01 + docid: + - type: BSI + id: PD 5500 + edition: 3 +- date: + - type: published + value: 2009-01 + docid: + - type: BSI + id: PD 5500 + edition: 4 +- date: + - type: published + value: 2012-01 + docid: + - type: BSI + id: PD 5500 + edition: 5 +- date: + - type: published + value: 2015-01 + docid: + - type: BSI + id: PD 5500 + edition: 6 +- date: + - type: published + value: 2018-01 + docid: + - type: BSI + id: PD 5500 + edition: 7 +- date: + - type: published + value: 2021-01 + docid: + - type: BSI + id: PD 5500 + edition: 8 +- date: + - type: updated + value: 2021-09 + - type: implemented + value: 2022-01 + docid: + - type: BSI + id: Amendment 1, tagged + amend: + description: SEE FOREWORD +- date: + - type: updated + value: 2022-09 + - type: implemented + value: 2023-01 + docid: + - type: BSI + id: Amendment 2, tagged + amend: + description: SEE FOREWORD +---- +-- + +It has the following renderings: + +* New style: ++ +___ +*Amendments issued since publication* + +|=== +| Date | Text affected + +| September 2021 | Amendment 1, tagged: SEE FOREWORD +| September 2022 | Amendment 2, tagged: SEE FOREWORD +|=== +___ + +* Old style: ++ +____ +*Publication history* + +First published as BS 5500 March 1976 + +Second edition January 1982 + +Third edition January 1985 + +Fourth edition January 1988 + +Fifth edition January 1991 + +Sixth edition January 1994 + +Seventh edition January 1997 + +First published as PD 5500 January 2000 + +Second edition January 2003 + +Third edition January 2006 + +Fourth edition January 2009 + +Fifth edition January 2012 + +Sixth edition January 2015 + +Seventh edition January 2018 + +Eighth edition January 2021 + +Ninth (present) edition + + +*Amendments/corrigenda issued since publication* + +|=== +|Issue Date | Effective Date | Amendment designation | Comments + +| September 2021 | January 2022 | Amendment 1, tagged| SEE FOREWORD +| September 2022 | January 2023 | Amendment 2, tagged| SEE FOREWORD +|=== +____ + +* Flex style: ++ +____ + +*Publication history* + +First published as BS 5500 March 1976 + +Second edition January 1982 + +Third edition January 1985 + +Fourth edition January 1988 + +Fifth edition January 1991 + +Sixth edition January 1994 + +Seventh edition January 1997 + +First published as PD 5500 January 2000 + +Second edition January 2003 + +Third edition January 2006 + +Fourth edition January 2009 + +Fifth edition January 2012 + +Sixth edition January 2015 + +Seventh edition January 2018 + +Eighth edition January 2021 + +Ninth (present) edition + + +*Amendments issued since publication* + +|=== +| Date | Text affected + +| September 2021 | Amendment 1, tagged: SEE FOREWORD +| September 2022 | Amendment 2, tagged: SEE FOREWORD +|=== +____ + + +=== Change markup + +In at least some documents, changes to documents in corrigenda and amendments are marked up with +arrows identifying the corrigendum or amendment. In order to replicate this markup, +changes should be notated as empty reviewer comments of type "corrigenda", with the reviewer identifier +as the conventional addendum or corrigendum label [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.1]. + +[source,asciidoc] +---- +[reviewer=A1,from=anchor1,to=anchor2,type=corrigenda] +**** +**** + + +[cols=3] +|=== +|[[anchor1]]IIB-P or Q +| Portland cement with 21% to 35% pozzolana +| CEM II/B-P or Q, CIIB-P or Q [[anchor2]] +|=== +---- + +Rendered as: + +____ + +[cols=3] +|=== +|`[A~1~>]` IIB-P or Q +| Portland cement with 21% to 35% pozzolana +| CEM II/B-P or Q, CIIB-P or Q `[> +---- + +[source,asciidoc] +---- +[.source%quoted] +<> +---- + +[source,asciidoc] +---- +[.source%modified] +<> +---- + +=== Colophon sections + +Expert commentaries are expected to include colophon sections: Author, technical reviewers, disclaimers: + +[source,asciidoc] +---- +[.colophon,type="authors"] +== Author + +Eamonn Hoxey ... + +[.colophon,type="reviewers"] +== Reviewers + +This commentary was peer-reviewed by .... + +[.colophon,type="disclaimer"] +== Disclaimer + +This commentary is commissioned text from expert authorities... +---- + +== Blocks + +=== Commentaries + +Commentaries are entered as notes of type `commentary`, +with an optional `target` attribute, +giving the anchor of the block the commentary is referencing. If no target +is given, the commentary is assumed to be about the subclause containing it. + +[source,asciidoc] +----- +[[reag]] +=== Reagents + +[NOTE,type=commentary,target=reag] +This is a commentary on the reagents + +[[table1]] +.Reagents in use +|=== +| A | B +|=== +----- + +____ +*7.6 Reagents* + +COMMENTARY ON CLAUSE 7.6 +This is a commentary on the reagents + +|=== +| A | B +|=== +_Table 1: Reagents in use_ +____ + +[source,asciidoc] +----- +[[reag]] +=== Reagents + +[NOTE,type=commentary] +This is a commentary on the reagents + +[[table1]] +.Reagents in use +|=== +| A | B +|=== +----- + +____ +*7.6 Reagents* + +COMMENTARY ON CLAUSE 7.6 +This is a commentary on the reagents + +|=== +| A | B +|=== +_Table 1: Reagents in use_ +____ + + +[source,asciidoc] +----- +=== Reagents + +[NOTE,type=commentary,target=table1] +This is a commentary on the table + +[[table1]] +.Reagents in use +|=== +| A | B +|=== +----- + +____ +*7.6 Reagents* + +COMMENTARY ON TABLE 1 +This is a commentary on the table + +|=== +| A | B +|=== +_Table 1: Reagents in use_ +____ + +=== Foreword notes + +BSI requires certain templated language to be incorporated into the foreword if applicable. +Of these, the paragraphs relating to _Product certification/inspection/testing_, +_Assessed capability_ and _Test laboratory accreditation_ should be entered as notes, +without their labels, and with the right type: `product-certification, `assessed-capability`, +`test-lab-accreditation`. + +[source,asciidoc] +----- +== Foreword + +... + +[NOTE,type=assessed-capability] +==== +Users of this part of BS 1234 are advised to consider +the desirability of quality system assessment and registration against the appropriate +standard in the BS EN ISO 9000 series by an accredited third-party certification body. +==== +----- + +____ +*Assessed capability.* Users of this part of BS 1234 are advised to consider +the desirability of quality system assessment and registration against the appropriate +standard in the BS EN ISO 9000 series by an accredited third-party certification body. +____ + +=== Lists + +Ordered lists are by default numbered according to BSI 0.2 Clause 23: rotating between +alphabetic, then arabic, then roman, both for multiple ordered lists at the same level, +and for levels of nesting within ordered lists. + +The styling can be overridden using attributes as is normal in Asciidoctor, e.g. +`[loweralpha]`, but in that case Metanorma will issue a warning. + +Ordered lists in BSI support the `start` attribute, to restart numbering; the value +of start is always numeric, regardless of how the list numbering is rendered. + +=== Figures + +Figures can optionally have a `width` attribute, with legal values `full-page-width`, `narrow`, +and `text-width` (default). + +[source,asciidoc] +---- +[width=narrow] +image::abc.png[] +---- + +[source,asciidoc] +---- +[.figure,width=narrow] +==== +image::abc.png[] +==== +---- + +=== Tables + +Tables can optionally have a `width` attribute, with legal values `full-page-width`, +and `text-width` (default). + +[source,asciidoc] +---- +[width=full-page-width] +|=== +|A |B + +|C |D +|=== +---- + +Tables can optionally have a second header row consisting of units. Any such header cells +should be marked up with `span:units[]`, to alert Metanorma not to render them in boldface: + +[source,asciidoc] +---- +[headerrows=2] +|=== +|Type |Linear density |Inside diameter +| |span:units[kg/mm] |span:units[mm] + +|Bone | 47 | 3.4 +|Tissue | 12 | 5.9 +|=== + +[headerrows=2] +|=== +3+>| span:units[Dimensions in millimeters] +|Type | Linear density | Inside diameter + +|Bone | 47 | 3.4 +|Tissue | 12 | 5.9 +|=== +---- + +Tables can have a horizontal rule drawn under a number of specified rows, through the `border-under-row` +attribute: this gives a comma-delimited list of row numbers, under which a thin border should be drawn. +Row counting starts with the first line of the header, as row #0: + +[source,asciidoc] +---- +[border-under-row="0,2",headerrows=2] +|=== +|Type |Linear density |Inside diameter +| |span:units[kg/mm] |span:units[mm] + +|Bone | 47 | 3.4 +|Tissue | 12 | 5.9 +|=== +---- + +renders as: + +.... +========================================= +Type Linear density Inside diameter +----------------------------------------- + kg/mm mm + +Bone 47 3.4 +----------------------------------------- +Tissue 12 5.9 +========================================= +.... + +Tables can contain a paragraph describing the provisions, although that is not preferred. This +is done by creating a cell spanning across all columns: + +[source,asciidoc] +---- +|=== +|Type |Length |Inside diameter + +|A |l_1 |d_1 +|B |l_1 |d_2 +3+| A paragraph containing a provision of the standard. +|=== +---- + diff --git a/author/cc/authoring.adoc b/author/cc/authoring.adoc index c6c1c4b5..a3b35f47 100644 --- a/author/cc/authoring.adoc +++ b/author/cc/authoring.adoc @@ -59,7 +59,7 @@ other committees are added as `_3`, `_4`... === Terms and Definitions [[note_general_doc_ref_terms_defs_calconnect]] -NOTE: This section supplements link:/author/topics/document-format/section-terms[The “Terms and Definitions” section] in general Metanorma documentation. +NOTE: This section supplements link:/author/topics/document-format/section-terms[The "Terms and Definitions" section] in general Metanorma documentation. This must be Clause 3. diff --git a/author/concepts/auto_numbering.adoc b/author/concepts/auto_numbering.adoc new file mode 100644 index 00000000..624b2392 --- /dev/null +++ b/author/concepts/auto_numbering.adoc @@ -0,0 +1,255 @@ +--- +layout: author-docs +title: Automatic numbering +--- +== Automatic numbering + +=== General +tag::auto-num-intro[] + +Metanorma supports auto-numbering for the following types of document elements ("`elements`"): + +* figures +* tables +* examples +* notes +* formulas +* sourcecode, pseudocode +* permissions, recommendations and requirements. + +NOTE: Users do not need to specify any numbering of these elements in their +source documents. + +The conventions for numbering vary by Metanorma flavour, but the +default is to number all elements consecutively in the main body of a document, and +separately in each Annex/Appendix, prefixed bt the Annex/Appendix number. + +NOTE: Typical AsciiDoc only supports auto-numbering of some block types, like +tables and figures. + + +=== Multi-level numbering + +Metanorma's auto-numbering functionality assigns numbers to elements consecutively. +Sometimes, more than one level of numbering is required for a sequence of elements; +for instance, _17a_, _17b_. + +To indicate that, all elements in the subsequence should be assigned the same +`subsequence` attribute of an autonumbered document element. + +The syntax is as follows: + +[source,asciidoc] +-- +[{block-type},subsequence={subsequence-id}] +-- + +Where: + +* `{block-type}` is type of the document block +* `{subsequence-id}` is the subsequence identifier + +[example] +.Example of using multiple subsequences for auto-numbering +==== +[source,asciidoc] +-- +[stem,subsequence=A] +++++ +A +++++ + +[stem,subsequence=A] +++++ +B +++++ + +[stem,subsequence=B] +++++ +C +++++ + +[stem,subsequence=B] +++++ +D +++++ + +[stem] +++++ +E +++++ +-- + +renders as: + +____ +A (1a) + +B (1b) + +C (2a) + +D (2b) + +E (3) +____ +==== + + +=== Unnumbered elements + +Sometimes a document element needs to be excluded from auto-numbering. +This is achieved by giving it the option attribute `%unnumbered`. + +Sourcecode and pseudocode snippets are by default numbered as figures +[added in https://github.com/metanorma/isodoc/releases/tag/v1.0.10]. If they +are not to be numbered, they need to be given the `%unnumbered` option attribute. + +The syntax is as follows: + +[source,asciidoc] +-- +// shorthand +[%unnumbered] +image::...[] + +// with other options +[options="unnumbered"] +image::...[] + +// block type with shorthand +[{block-type}%unnumbered] +image::...[] + +// block type with other options +[{block-type},options="unnumbered"] +image::...[] +-- + +Where: + +* `{block-type}` is type of the document block; +* The `%` symbol is a shorthand for `options="unnumbered"`. + +NOTE: The `%` shorthand cannot be used in the presence of block arguments or +attributes, such as `[source,c]` or `[source,type="..."]`. In this case, the +`options="unnumbered"` should be spelled out. + + +[example] +.Example of an unnumbered figure +==== +[source,asciidoc] +-- +[[figureC-1]] +[%unnumbered] +.Typical gelatinization curve +image::rice_images/rice_image2.png[] +-- +==== + +[example] +.Example of an unnumbered source block +==== +Both of these blocks are identical. + +[source,asciidoc] +-- +[source%unnumbered] +---- +for (i = 0; i < n; i++) { bounce(v[i], wall) } +---- +-- + +[source,asciidoc] +-- +[source,options="unnumbered"] +---- +for (i = 0; i < n; i++) { bounce(v[i], wall) } +---- +-- +==== + +[example] +.Example of an unnumbered source block with syntax highlighting (from RNP) +==== +[source,asciidoc] +-- +[source,cpp,options="unnumbered"] +---- +/* print a usage message */ +static void +print_usage(const char *usagemsg) +{ + cli_rnp_print_praise(); + ERR_MSG("%s", usagemsg); +} +---- +-- +==== + +[example] +.Example of an unnumbered pseudocode block +==== +[source,asciidoc] +-- +[%unnumbered] +[pseudocode] +---- +stem:[forall v_{i}] *bounce* stem:[v_{i}] off the wall +---- +-- +==== + + +=== Prevention of double-numbering + +If a document element is included in a block type that is already subject to +numbering, it will be excluded from auto-numbering. + +This means that tables, sourcecode and pseudocode, and figures are +excluded from auto-numbering within +examples, requirements, recommendations, permissions, tables, figures, +sourcecode and pseudocode. +{blank}[added in https://github.com/metanorma/isodoc/releases/tag/v1.0.11] + + +[[numbering-override]] +=== Override numbering + +There are circumstances when auto-numbering of elements needs to be overriden; +for instance, numbering out of sequence in updated documents. + +In these cases, elements can be given an optional `number` +attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1], +assigning a required document element number to override auto-numbering. + +Elements subsequent to that element will be auto-numbered so as to +follow the previous element, so long as the supplied number belongs +to the same sequence. + +For subsequences, number shall have only subsequence scope. + +The syntax is as follows: + +[source,asciidoc] +-- +[{block-type},number={number-to-use}] +-- + +Where: + +* `{block-type}` is type of the document block +* `{number-to-use}` is an integer specifying at which number to use + +[example] +.Example of manually specifying numbering of a document block +==== +[source,asciidoc] +-- +[source,number=7] +---- +for (i = 0; i < n; i++) { bounce(v[i], wall) } +---- +-- +==== diff --git a/author/topics/building/reference-lookup.adoc b/author/concepts/automatic-reference-lookup.adoc similarity index 99% rename from author/topics/building/reference-lookup.adoc rename to author/concepts/automatic-reference-lookup.adoc index 49e94c79..5188d8a2 100644 --- a/author/topics/building/reference-lookup.adoc +++ b/author/concepts/automatic-reference-lookup.adoc @@ -1,9 +1,7 @@ --- layout: author-docs +title: Automatic reference lookup using Relaton --- - -= Automatic reference lookup - == General For references to certain standards, Metanorma will attempt to look up references online diff --git a/author/concepts/best_practice_project_structure.adoc b/author/concepts/best_practice_project_structure.adoc new file mode 100644 index 00000000..674ff138 --- /dev/null +++ b/author/concepts/best_practice_project_structure.adoc @@ -0,0 +1,8 @@ +--- +layout: author-docs +--- += Best practices for structuring a Metanorma project + +//Discuss single file approach vs. multi file approach and referencing + +//Building often to troubleshoot incrementally and spot errors early diff --git a/author/concepts/deep-dive-cross-references.adoc b/author/concepts/deep-dive-cross-references.adoc new file mode 100644 index 00000000..b7dc6fd2 --- /dev/null +++ b/author/concepts/deep-dive-cross-references.adoc @@ -0,0 +1,108 @@ +--- +layout: author-docs +title: Deep-dive into cross-references +description: This article looks at the technical details of cross-references in Metanorma AsciiDoc. If you want to learn how to insert cross-references, read link:author/topics/inline_markup/links.adoc[Adding links and cross-references] +--- +== Basic anchor syntax + +The basic mechanism for cross-references is setting anchors to place that should be referenced. + +.Example of an anchor and a reference +[source,asciidoc] +-- +[[anchor-id]] +== Target clause + +The requirements are... + +== Reference clause + +As seen in <>... +-- + +=== Valid anchor IDs + +Anchor IDs of any type (cross-references, items, bibliographies, etc.) are directly +converted into XML, and therefore *must not* contain the following: + +* colons +* whitespaces or; +* words starting with numbers. + +These cases are not supported in XML; permitted characters are specified by the link:https://www.w3.org/TR/xml-names11/#NT-NCName[NCName attribute for Namesapece Declaration]. + +Colons in cross-references are used for +link:/author/topics/document-format/collections#indirect-xrefs[indirect cross-references between files in the same collection], +to delimit namespaces and containers from anchor IDs [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4]. + +== Unambiguous referencing + +Cross-reference text in Metanorma adheres to guidance given in +*ISO/IEC DIR 2* for internal cross-references, in order to guarantee unambiguous referencing. + +In particular, if a formula, example, figure, list, list item or table is cross-referenced outside its (sub)clause, the clause containing the item is always given in the cross-reference, unless the item is being referenced in the same clause. + +In the case of notes, the containing clause is extended to containing example, figure or table. + +NOTE: +[example] +==== +For example, in the Metanorma ISO Rice model sample document +formula B.1 is defined in Annex B.6, and is referenced in B.6 and B.7. + +In the Rice model document published by ISO, both instances are cited as "`Formula (B.1)`". +However, Metanorma follows ISO/IEC DIR 2 in citing the former +as "`Formula (B.1)`", but the latter as "`B.6, Formula (B.1)`". +==== + +In this sense, Metanorma is "`more royalist than the king`" in applying formatting rules and +validation—which is what you would want of a computer-based tool. + +The label of the item cross-referenced, the use of brackets, and the containing reference +are all taken care of by Metanorma; the document author needs only give the item identifier +in the AsciiDoc source +(e.g. `\<<``formulaB-1``>>` generates either "`Formula (B.1)`" or "`B.6, Formula (B.1)`", +depending on where in the document it occurs.) + +=== Dropping cross-reference labels and prefixes + +If the cross-reference is given with `droploc%` as its text, then the label and prefix +are dropped: the cross-reference value is given in +isolation [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.4]. + +This can be done for example for ranges: + +[source,asciidoc] +---- +Clauses <> to <> +---- + +to be rendered as e.g. + +____ +Clauses 7 to 9 +____ + +== Localities in Metanorma AsciiDoc + +In vanilla AsciiDoc, any text in a cross-reference that follows a comma constitutes custom text for the cross-reference. + +So a cross-reference `\<>` would be rendered as "`the foregoing reference`", and hyperlinked to the `ISO7301` reference. + +In *Metanorma AsciiDoc cross-references*, bibliographic localities +(e.g. page numbers, clause numbers) can be added directly after the comma, +as part of the cross-reference text. + +[example] +==== +EXAMPLE: "`ISO 7301, Clause 2, Table 1a, pp. 7-9`" would be expressed as: + +[source,asciidoc] +-- +<> +-- +==== + +Read more about link:/author/topics/sections/bibliography#localities[localities and locality values] in the Bibliography documentation. + +//Write a short summary of the article? \ No newline at end of file diff --git a/author/concepts/intro_to_asciidoc.adoc b/author/concepts/intro_to_asciidoc.adoc new file mode 100644 index 00000000..9d67e2f0 --- /dev/null +++ b/author/concepts/intro_to_asciidoc.adoc @@ -0,0 +1,27 @@ +--- +layout: author-docs +--- += Introduction to Metanorma AsciiDoc + +tag::tutorial[] +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. + +An AsciiDoc document consists of different levels of granularity: + +* The document head (also called the header) +* Sections +* Blocks +* Inline markup +end::tutorial[] + +The https://asciidoctor.org/docs/user-manual/[Asciidoctor manual] provides ample information about the general markup mechanisms of typical AsciiDoc. + +== Unsupported AsciiDoc features +While Metanorma mostly *adds* functionality to the AsciiDoc markup language, there are also some mechanisms, that Metanorma does not support: + +* Sidebars (``aside``s) are not supported. Instead, they are used for link:./reviewer-notes/[reviewer comments]. +* Page breaks (`thematic break`) are not supported. +* ASCII art/preformatted text (`literal`) are not supported in most Metanorma flavors. + diff --git a/author/concepts/metanorma_workflow.adoc b/author/concepts/metanorma_workflow.adoc new file mode 100644 index 00000000..ecaf2af7 --- /dev/null +++ b/author/concepts/metanorma_workflow.adoc @@ -0,0 +1,97 @@ +--- +layout: author-docs +title: The Metanorma workflow +--- +tag::tutorial[] +The Metanorma workflow consists of six phases: + +. Document creation +. Editing the document +. Validation +. Output generation +. Review +. Publication + + +.The Metanorma Workflow from start to finish +image::/assets/author/concepts/Metanorma_Workflow.png[The Metanorma workflow] + +== Document creation +tag::creation[] +You can create a new standard document either by: + +* Creating a new, empty AsciiDoc file +* Using a template +* Importing a Word Document + +*New file* + +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. + +*Import from Word* + +Importing from Word makes sense if you are moving from Word to Metanorma and need to move several, large documents. To facilitate the migration, you can use the import tool called https://github.com/metanorma/reverse_adoc/[Reverse AsciiDoc]. However, the imports are not always perfect, so you need to be familiar with the Metanorma and know how to resolve error messages. If you new to Metanorma, the simplest way is to transfer your content into Metanorma AsciiDoc manually. +end::creation[] +tag::editing[] +== Editing the document + +You can edit Metanorma documents in any plain-text editor because they only consist of text. The next lesson will introduce you to the basics of AsciiDoc. +These editors have been reported to work well for writing Metanorma AsciiDoc: + +* https://atom.io/[Atom] with https://atom.io/users/asciidoctor[Asciidoctor plugins] +* https://code.visualstudio.com/[Microsoft Visual Studio Code] with https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode[AsciiDoc extension] for live preview +end::editing[] + +== Validation + +Before you can generate any outputs, the AsciiDoc document needs to be checked against the document model to ensure it follows the rules of your SDO. Since the document model is defined in an XML schema, the compiler converts the AsciiDoc document into an XML file. The XML file is then checked against the SDO's XML schema. Metanorma will log all deviations from the SDO's structure or formatting on the terminal and into an error file. + +* ❌ Invalid XML: The XML file does not comply with the XML schema, or with the formatting rules defined by the SDO. +All errors are logged to the terminal and are saved to an Error file (.`err`). Often the document will render successful despite errors, but the error messages point out potential issues with the document structure. + +* ✅ Valid XML: The XML file complies with the XML schema and the compiler can proceed to generate an output. + +== Output generation + +The Metanorma toolchain compiles documents in the following formats: + +* Metanorma XML +* HTML +* PDF +* Microsoft Word + +*Metanorma XML* + +Metanorma always generates an XML output first because it is the intermediate format used to drive the other formats. The Metanorma XML file marks up the semantic content of the standards document and is therefore used during the validation stage. Metanorma then generates a presentation version of the XML (`.presentation.xml`), which resolves cross-references, captions, and internationalisation, and is used as the basis of all other formats. + +*HTML* + +The HTML output is in HTML 5. All HTML output has a sidebar with a Javascript-generated table of contents, which is two section levels deep. Audio and video files are not supported. + +*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* + +Metanorma can also generate a `.doc` Word output. Metanorma does not output `.docx` because it is easier to support all of the formatting requirements in a `.doc` file. + +== Review + +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. + +end::tutorial[] + +=== Related links + +* link:../topics/creating_new_document.adoc[Creating a new document from a template] +* Word import Tool: https://github.com/metanorma/reverse_adoc[Reverse AsciiDoc] +* For more on why Metanorma uses .doc, see https://github.com/metanorma/html2doc/wiki/Why-not-docx%3F[Why not .docx] + diff --git a/author/concepts/what_is_metanorma.adoc b/author/concepts/what_is_metanorma.adoc new file mode 100644 index 00000000..9a7a18a7 --- /dev/null +++ b/author/concepts/what_is_metanorma.adoc @@ -0,0 +1,34 @@ +--- +layout: author-docs +--- += What is Metanorma? + +tag::tutorial[] + +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 link:/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 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 +image::/assets/author/concepts/complexity_pyramid.png[Three layers of complexity: AsciiDoc - Metanorma AsciiDoc - Flavour specific document rules] + + +Metanorma has many advantages for authoring standards: + +* Metanorma supports the needs of many standardization organizations, such as ISO, IETF, and many more. +* Metanorma can be extended with new document models (flavors). +* It uses the "what you see is what you mean" (WYSIWYM) approach based on AsciiDoc. +* You can style your content differently, depending on the output. +* The document models ensure complete and consistent standard documents that follow the rules of your organization. +* Metanorma can create long and complex documents without them becoming corrupted. +* Metanorma enables dynamic integration of external data into documents. + +end::tutorial[] diff --git a/author/concepts/wysiwyg_vs_wysiwym.adoc b/author/concepts/wysiwyg_vs_wysiwym.adoc new file mode 100644 index 00000000..cef7976e --- /dev/null +++ b/author/concepts/wysiwyg_vs_wysiwym.adoc @@ -0,0 +1,24 @@ +--- +layout: author-docs +--- += Is what you see what you get? + +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: + +* Creating Documents quickly +* An intuitive interface +* Printer prints exactly what you see on your screen = What you see is what you get (WYSIWYG) + +.Word is a WYSIWYG application +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. + +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] +end::tutorial[] \ No newline at end of file diff --git a/author/iec.adoc b/author/iec.adoc index 3f6a8371..0bd11287 100644 --- a/author/iec.adoc +++ b/author/iec.adoc @@ -18,7 +18,7 @@ The syntaxes of ISO and IEC documents are identical, as defined in ISO/IEC Directives, Part 2:2018 (https://www.iec.ch/members_experts/refdocs/iec/isoiecdir2%7Bed8.0.RLV%7Den.pdf[IEC version (PDF link)], https://www.iso.org/sites/directives/current/part2/index.xhtml[ISO version (HTML link)]); -please refer to https://www.metanorma.org/author/iso/[Metanorma-ISO documentation]. +please refer to link:/author/iso/[Metanorma for ISO]. {% include flavor-quickstart-steps.adoc flavor=layout.iso_flavor %} diff --git a/author/ieee/authoring-guide/bibliographic-references.adoc b/author/ieee/authoring-guide/bibliographic-references.adoc index 6ad2400c..f45430b2 100644 --- a/author/ieee/authoring-guide/bibliographic-references.adoc +++ b/author/ieee/authoring-guide/bibliographic-references.adoc @@ -3,7 +3,7 @@ layout: ieee-flavor title: Bibliographic references --- //General Bibliography -//include::/author/topics/sections/entering_bib.adoc[tag=tutorial] +//include::/author/topics/sections/entering-bib.adoc[tag=tutorial] == General diff --git a/author/ieee/authoring-guide/block-syntax.adoc b/author/ieee/authoring-guide/block-syntax.adoc index 15272015..2758f63b 100644 --- a/author/ieee/authoring-guide/block-syntax.adoc +++ b/author/ieee/authoring-guide/block-syntax.adoc @@ -149,7 +149,7 @@ Tables are a useful tool to collect and display measured data. As AsciiDoc is al |=== <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. <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. @@ -165,7 +165,7 @@ NOTE: In typical AsciiDoc, `[cols="3"]` is considered a shorthand to `[cols="1,1,1"]`, but this is not supported in Metanorma AsciiDoc. -include::author/ogc/topics/markup.adoc[tag=tables-ogc] +include::../../../author/ogc/topics/markup.adoc[tag=tables-ogc] == Images @@ -191,7 +191,7 @@ P:: point of the curve corresponding to a cooking time of stem:[t_90] == Admonitions -Admonitions are signal words used to catch the reader's attention, such as “TIP”, “NOTE”, or “WARNING”. There are two ways to declare an admonition: in a single paragraph and as a block. +Admonitions are signal words used to catch the reader's attention, such as "TIP", "NOTE", or "WARNING". There are two ways to declare an admonition: in a single paragraph and as a block. == Single-paragraph admonitions @@ -309,4 +309,4 @@ required AsciiDoc markup. == Removing auto-numbering from blocks -include::author/ogc/topics/markup.adoc[tag=unnumbered-ogc] +include::../../../author/ogc/topics/markup.adoc[tag=unnumbered-ogc] diff --git a/author/ieee/authoring-guide/cross-references.adoc b/author/ieee/authoring-guide/cross-references.adoc index 3c62cae9..79cd71d0 100644 --- a/author/ieee/authoring-guide/cross-references.adoc +++ b/author/ieee/authoring-guide/cross-references.adoc @@ -12,7 +12,7 @@ The main mechanism for references are anchors and destinations. There are the following types of cross-references: -// * link:/author/topics/sections/entering_bib.adoc[Bibliographic entries] +// * link:/author/topics/sections/entering-bib.adoc[Bibliographic entries] * link:/author/topics/document-format/xrefs[Internal references] * link:/author/topics/document-format/bibliography[Bibliographic entries] * Hyperlinks to external sources (e.g., a link to a website) diff --git a/author/ieee/authoring-guide/metadata.adoc b/author/ieee/authoring-guide/metadata.adoc index 2c5bbaa4..752af63d 100644 --- a/author/ieee/authoring-guide/metadata.adoc +++ b/author/ieee/authoring-guide/metadata.adoc @@ -209,20 +209,8 @@ entered: * balloting committee members * SA standardization board members -In IEEE SA, a working group operate under one of two modes: -"individual mode" or "entity mode". +All membership information is encoded in a participants clause. -If the working group operates under individual mode: - -* the participants of the working mode should be entered, as individuals - -If the working group operates under entity mode: - -* the representatives of entities that are members of the working group -are to be entered; -* the individual participants of the working mode should be entered, as -individuals; -* the entity members of the working group should be entered. // The individual contributors that created the document, this is set via the // `:fullname:` and `:role:` attributes. Additional contributors are set by @@ -230,77 +218,25 @@ individuals; // e.g. For `:fullname_2:` use `:role_2:`. -.Usage of contributor information for an individual mode working group +.Usage of authorship information outside of memberships [example] ==== ---- :society: Computer Society <1> :committee: C/AISC - Artificial Intelligence Standards Committee <2> :working-group: Spatial Web Working Group <3> -:wg-chair: Gabriel Rene <4> -:wg-vicechair: Michael Wadden <5> -:wg-secretary: Christine Perey <6> ----- -<1> IEEE Society. -<2> IEEE Committee sponsor of the document. -<3> IEEE SA working group that produces the document. -<4> Working group chair. -<5> Working group vice chair. -<6> Working group secretary. -List of working group members (entity). -==== - - -.Usage of contributor information (entity mode working group) -[example] -==== ----- -:society: Computer Society <1> -:committee: Standards Activities Board <2> -:working-group: Shared Machine Learning <3> -:wg-chair: Jin Peng <4> -:wg-vicechair: Cheng Hong <5> -:wg-members: Alibaba China Co. Ltd.; Alipay Technology Co., Ltd; ... <6> ---- <1> IEEE Society. <2> IEEE Committee sponsor of the document. <3> IEEE SA working group that produces the document. -<4> Working group chair. -<5> Working group vice chair. -<6> List of working group members (entity), semi-colon delimited. ==== -.Entry of balloting group members (entity mode working group) -[example] -==== -[source,adoc] ----- -:balloting-group: Standards Association <1> -:balloting-group-members: 0xSenses Corporation; AAC Technologies; ... <2> ----- -<1> Balloting group name. -<2> Balloting group members. -==== +== Participants and contributors +tag::participants-ieee[] -.Entry of standardization board members -[example] -==== -[source,adoc] ----- -:std-board-chair: Gary Hoffman <1> -:std-board-vicechair: Jon Walter Rosdahl <2> -:std-board-pastchair: John D. Kulick <3> -:std-board-secretary: Konstantinos Karachalios <4> -:std-board-members: Edward A. Addy; Doug Edwards; ... <5> ----- -<1> IEEE SA Standardization Board Chair. -<2> IEEE SA Standardization Board Vice Chair. -<3> IEEE SA Standardization Board Past Chair. -<4> IEEE SA Standardization Board Secretary. -<5> IEEE SA Standardization Board members, semicolon-delimited. -==== +include::../../../author/ieee/topics/markup.adoc[tag=participants-ieee] == Table of contents: figures and tables diff --git a/author/ieee/authoring-guide/sections.adoc b/author/ieee/authoring-guide/sections.adoc index 11b745d7..83ea3e3a 100644 --- a/author/ieee/authoring-guide/sections.adoc +++ b/author/ieee/authoring-guide/sections.adoc @@ -21,7 +21,7 @@ Typically, an IEEE SA document contains the following content order: * <> [[preliminary]] -include::author/ieee/topics/markup.adoc[tag=preliminary-ieee] +include::../../../author/ieee/topics/markup.adoc[tag=preliminary-ieee] [[terms]] == Terms and definitions diff --git a/author/ieee/authoring-guide/terms-definitions.adoc b/author/ieee/authoring-guide/terms-definitions.adoc index ddc6b643..2f1e6d2e 100644 --- a/author/ieee/authoring-guide/terms-definitions.adoc +++ b/author/ieee/authoring-guide/terms-definitions.adoc @@ -33,8 +33,8 @@ terminology entries to be made available in the definitions clause. [quote,IEEE SA Style Manual 2021, 12.4.2 General terminology usage] ____ English words should be used in accordance with their definitions in the latest -edition of Merriam-Webster’s New Collegiate Dictionary. Electrical and -electronics terms not defined in Merriam-Webster’s New Collegiate Dictionary +edition of Merriam-Webster's New Collegiate Dictionary. Electrical and +electronics terms not defined in Merriam-Webster's New Collegiate Dictionary should be used in accordance with their definitions in the Dictionary Online. The Dictionary is a continually-updated electronic version of the former IEEE 100, The Authoritative Dictionary of IEEE Standards Terms. diff --git a/author/ieee/authoring-guide/terms.adoc b/author/ieee/authoring-guide/terms.adoc index b0030801..d30d8fdd 100644 --- a/author/ieee/authoring-guide/terms.adoc +++ b/author/ieee/authoring-guide/terms.adoc @@ -143,4 +143,4 @@ suggested but no clear-cut recommendations are made SOURCE: https://standards.ieee.org/wp-content/uploads/import/documents/other/ieee_sa_toolkit.pdf[IEEE SA Quick Reference Guide: Standards Development Process] -These levels of requirements are often shown by the use of particular “standards verbs,” i.e., “shall” for requirements, “should” for recommendations, and “may” for guidelines. (more information can be found in the IEEE SA Standards Board Operations Manual and the IEEE SA Standards Style Manual) Figuring out what level of requirement is needed helps determine what kind of document should be developed. +These levels of requirements are often shown by the use of particular "standards verbs," i.e., "shall" for requirements, "should" for recommendations, and "may" for guidelines. (more information can be found in the IEEE SA Standards Board Operations Manual and the IEEE SA Standards Style Manual) Figuring out what level of requirement is needed helps determine what kind of document should be developed. diff --git a/author/ieee/authoring-guide/text-formatting.adoc b/author/ieee/authoring-guide/text-formatting.adoc index 767f20d3..b45d31e7 100644 --- a/author/ieee/authoring-guide/text-formatting.adoc +++ b/author/ieee/authoring-guide/text-formatting.adoc @@ -13,7 +13,7 @@ include::author/topics/inline_markup/footnotes.adoc[tag=tutorial] If OGC produces an Index, include this section, too == Index Terms -include::author/topics/inline_markup/index.adoc[tag=tutorial] +include::author/topics/inline_markup/index_terms.adoc[tag=tutorial] //// // Include 1: inline_markup.adoc @@ -72,20 +72,20 @@ Metanorma extends these simple formats with: //renders as: .Illustration of strikethrough text in Metanorma. -image::/assets/author/topics/document-format/text/fig-strikethrough.png[Illustration of strikethrough text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-strikethrough.png[Illustration of strikethrough text in Metanorma,width=500] .Illustration of small caps text in Metanorma. -image::/assets/author/topics/document-format/text/fig-smallcaps.png[Illustration of small caps text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-smallcaps.png[Illustration of small caps text in Metanorma,width=500] .Illustration of underlined text in Metanorma. -image::/assets/author/topics/document-format/text/fig-underline.png[Illustration of underlined text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-underline.png[Illustration of underlined text in Metanorma,width=500] //Include 3: markup.adoc == OGC specific text markup -include::author/ogc/topics/markup.adoc[tag=inline-ogc] +include::../../../author/ogc/topics/markup.adoc[tag=inline-ogc] //Include 4: text_formatting.adoc == Character substitutions diff --git a/author/ieee/ref/document-attributes.adoc b/author/ieee/ref/document-attributes.adoc index a1b87545..aa86a231 100644 --- a/author/ieee/ref/document-attributes.adoc +++ b/author/ieee/ref/document-attributes.adoc @@ -28,6 +28,11 @@ For an _introduction to Metanorma AsciiDoc document attributes_ and how Metanorm ---- ==== +`partnumber`:: The document part number, where applicable [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12]. +`subpartnumber`:: The document subpart number, where applicable [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12]. + +`conformance`:: Specification of the conformance of the document, where applicable (e.g. _Conformance_ `02-2021`) [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12]. + `draft`:: The draft number. Use together with `:docstage: draft`. Do not include the initial "D". + .Example for IEEE SA `docstage` @@ -137,6 +142,8 @@ Document subtype. Choices: `amendment`:: Document is an amendment `corrigendum`:: Document is an corrigendum `erratum`:: Document is an erratum +`icap`:: Document is an ICAP (IEEE Conformity Assessment Program) document (applies only to `whitepaper`) +`industry-connections-report`:: Document is an Industry Connnections Report document (applies only to `whitepaper`) -- `trial-use`:: Document published for a limited period of time. @@ -149,7 +156,7 @@ NOTE: Please see https://standards.ieee.org/about/policies/opman/sect5/[Operations Manual, 5.7 Trial-Use standards] for more details. -`issued-date`:: The date on which the document was approved. +`issued-date`:: The date on which the document was approved. (Applicable to drafts.) Like all dates in Metanorma, this must be supplied in `YYYY-MM-DD` format. + .Example for IEEE SA `issued-date` @@ -216,14 +223,19 @@ clauses. Metanorma will not supply the "Word usage" subclause and will not generate or modify the "Participants" clause. +`:program:`:: Program under which a white paper was authored [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.1.6]. == Document relationships `:merges:`:: This document incorporates the document(s) with the nominated -identifiers (semicolon-delimited). +identifiers (semicolon-delimited). In IEEE identifiers, indicated as _incorporated_. `:updates:`:: This document is an update of the document(s) with the nominated -identifiers (semicolon-delimited). +identifiers (semicolon-delimited). Applies to revisions, as well as to appendices +and corrigenda. + +`:supplements:`:: This document is a supplement of the document with the nominated +identifier [added in https://github.com/metanorma/isodoc/releases/tag/v1.0.12]. [[document-contributors]] @@ -306,6 +318,7 @@ An IEEE SA working group can be one of two modes * Individual-based: members are individual contributors `working-group`:: The working group responsible for the document. +Include any final "Working Group" text in the group name. + .Example for IEEE SA `working-group` [example] @@ -316,6 +329,8 @@ An IEEE SA working group can be one of two modes ---- ==== +(Rendered as: _the Spatial Web Working Group had the following membership:..._) + Members of the working group are to be listed in the link:/author/ieee/topics/markup#participants[Participants clause]. @@ -329,6 +344,8 @@ The balloting group is composed of voting members of the working group, or the committee that the working group belongs to. `balloting-group`:: The Standards Association balloting group responsible for the document. +Do not supply the final "Standards Association balloting group" text in the group name; +that is supplied by Metanorma. `balloting-group-type`:: The type of the Standards Association balloting group responsible for the document, _individual_ or _entity_ (default: _individual_). @@ -344,6 +361,49 @@ in the document preface. Members of the IEEE SA Standardization Board (SASB) are to be listed in the link:/author/ieee/topics/markup#participants[Participants clause]. +=== Personal authors + +White papers require personal authors to be specified, as follows: + +* `:surname:`, `:surname_2:`, `:surname_3:`: Surname of personal authors +* `:givenname:`, `:givenname_2:`, `:givenname_3:`: Given name of personal authors +* `:contributor-position:`, `:contributor-position_2:`, `:contributor-position_3:`: Job title of personal authors + +=== Sponsors + +The sponsoring bodies, if any, are indicated through the `:sponsor:` and `:sponsor-subdivision:` +attributes. As with other author values, multiple instances of sponsoring organisations and their +subdivisions are indicated as `:sponsor_2:` and `:sponsor-subdivision_2:`, `:sponsor_3:` and `:sponsor-subdivision_3:`, etc. + +The values of `:sponsor-subdivision_{i}:` in turn +can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), +and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, +from larger to smaller) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]; +the different hierarchical levels can optionally be prefixed with type and a colon. +On the front line, if it is a sponsor, "IEEE" is prefixed to the first subdivision, rather than being rendered on a separate line. + +The following is an example of how two divisions of the IEEE are indicated as sponsoring the document: + +[source,adoc] +---- +:sponsor: IEEE +:sponsor-subdivision: "Power & Energy Society", Power System Communications Committee; Communications Society, Standards Committee +---- + +rendered as: + +____ +Sponsored by the + +*Power System Communications Committee* + +of the + +*IEEE Power & Energy Society* + +and the + +*Standards Committee* + +of the + +*IEEE Communications Society* +____ + +NOTE: the quotation marks are needed to process the CSV correctly. == Visual appearance diff --git a/author/ieee/topics/markup.adoc b/author/ieee/topics/markup.adoc index 52cfce48..ed412ed3 100644 --- a/author/ieee/topics/markup.adoc +++ b/author/ieee/topics/markup.adoc @@ -107,9 +107,14 @@ in a <> clause) interpreted + +end::preliminary-ieee[] + + [[participants]] == Participants and contributors +tag::participants-ieee[] === General There are multiple types of contributors to an IEEE SA document, and the @@ -452,8 +457,25 @@ NOTE: The standards board membership is provided by the working group secretary or the IEEE editor during editing. If the information is not provided in the document, dummy values will be provided to match those in the IEEE templates. +=== Name markup -end::preliminary-ieee[] +The forenames and surnames of participants should be marked up semantically as such, +for correct generation of Word styles. This is done with the markup +`span:surname[]`, `span:forename[]`, and [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.2.1]. +There is no need to mark up the role of participants or their status as companies, as this is already semantically +differentiated in markup. + +[source,adoc] +---- +item:: +name::: span:forename[Justin] span:surname[Refice] +role::: Chair +item:: +name::: span:forename[Mark] span:surname[Strickland] +role::: Vice Chair +---- + +end::participants-ieee[] == Overview @@ -482,6 +504,9 @@ References are automatically sorted by Metanorma: * Bibliography references are automatically sorted by designators or author and title. +Footnotes are automatically inserted for withdrawn IEEE references, and for references +from Standards Defining Organizations recognised in Relaton [added in https://github.com/metanorma/metanorma-ieee/releases/tag/v1.1.11]. + The bibliography is entered as a subclause of an annex: the bibliography heading is overwritten by the annex heading, but it must still be given as "Bibliography" to be recognised correctly. diff --git a/author/ietf/ref/document-attributes.adoc b/author/ietf/ref/document-attributes.adoc index 8b0d9796..923663d2 100644 --- a/author/ietf/ref/document-attributes.adoc +++ b/author/ietf/ref/document-attributes.adoc @@ -161,6 +161,7 @@ Set document submission type for this document. The following values are allowed * `independent` * `IAB` * `IRTF` +* `editorial` + RFC XML: `rfc@submissionType` and `rfc/front/seriesInfo@stream`. + @@ -216,11 +217,11 @@ with the URL of the Internet Draft on the IETF-controlled web site that retains copies of Internet-Drafts. RFC XML: `front/link[@rel = 'convertedFrom']/@href` -`:instance:`:: +`:instance-of:`:: (Any status) URL for any alternate representation of this document. RFC XML: `front/link[@rel = 'alternate']/@href` [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v2.0.8] + -NOTE: Formerly this was called `:equivalent:`. +NOTE: Formerly this was called `:equivalent:` and `:instance:`. `:submission-type:`:: Optional. Document stream of document described in diff --git a/author/ietf/topics/markup.adoc b/author/ietf/topics/markup.adoc index 4fff069b..8af2dc82 100644 --- a/author/ietf/topics/markup.adoc +++ b/author/ietf/topics/markup.adoc @@ -288,22 +288,22 @@ sqrt(4) = 2 [source,asciidoc] -- [[id]] <1> -[nobullet=true,spacing=normal|compact] <2> +[nobullet=true,spacing=normal|compact,indent=5,bare=true] <2> * Unordered list 1 <3> * Unordered list 2 <3> ** Nested list <4> [[id]] <5> -[spacing=compact,start=n,group=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman] <6> +[spacing=compact,start=n,group=n,format=List #%d,arabic|loweralpha|upperralpha|lowerroman|upperroman,indent=5] <6> . A <7> . B <7> -- <1> `ul/@anchor` -<2> `ul/@empty`, `ul/@spacing` +<2> `ul/@empty`, `ul/@spacing`, [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2] `ul/@indent`, `ul/@bare` <3> `ul/li/t` <4> `ul/li/t/ul/li/t` <5> `ol/@anchor` -<6> `ol/@spacing`, `ol/@start`, `ol/@group`, `ol/@type = "#%d", `ol/@type` (for arabic|loweralpha|upperralpha|lowerroman|upperroman) +<6> `ol/@spacing`, `ol/@start`, `ol/@group`, `ol/@type = "#%d", `ol/@type` (for arabic|loweralpha|upperralpha|lowerroman|upperroman), [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2] `ol/@indent` <7> `ol/li/t` === Definition Lists @@ -401,11 +401,11 @@ This is done in AsciiDoc by prefixing the table cell with `a|`. [source,asciidoc] -- [[id]] <1> -[keep-with-next=true,keep-with-previous=true] <2> +[keep-with-next=true,keep-with-previous=true,indent=5] <2> Paragraph text <3> -- <1> `t/@anchor` -<2> `t/@keepWithNext`, `t/@keepWithPrevious` +<2> `t/@keepWithNext`, `t/@keepWithPrevious`, [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2] `t/@indent` <3> `Paragraph text` === Quotes @@ -488,9 +488,8 @@ Profile?! This ((indexterm)) <1> is visible in the text, this one is not (((indexterm, index-subterm))). <2> - -This is a ((primary:primary index term)) <3> , and so is -(((primary:indexterm, inxex-subterm))) <4> . +This is a ((primary:primary index term)) <3> +and so is (((primary:indexterm, index-subterm))) <4> -- <1> `indexterm` <2> `` @@ -542,12 +541,16 @@ Content content content <> <1> <> <2> <> <3> -http://example.com/[linktext] <4> +http://example.com/[] <4> +http://example.com/[linktext] <5> +http://example.com/[style=angle%] <6> ---- <1> `` <2> `text` <3> `text` -<4> `linktext` +<4> `` +<5> `linktext` +<6> `` [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v3.3.1] Note that fragments (e.g. `crossreference#fragment`) are not supported on the `xref/@target` attribute: the RFC XML specification requires that the @@ -567,15 +570,18 @@ default, naming and numbering the referenced object. <> <4> <> <5> ---- -<1> `` -<2> `` -<3> `text` -<4> `` -<5> `text` +<1> `` +<2> `` +<3> `text` +<4> `` +<5> `text` Localities other than `clause` and `section` are ignored in the generated RFC XML v3. +Metanorma has switched to `xref` in its RFC XML output from the deprecated +`relref` [added in https://github.com/metanorma/metanorma-ietf/releases/tag/v3.3.1]. + === Footnotes Footnotes in text are rendered as a separate "`Endnotes`" appendix, with each diff --git a/author/ietf/topics/references.adoc b/author/ietf/topics/references.adoc index 8e53e5cf..58d7fa5b 100644 --- a/author/ietf/topics/references.adoc +++ b/author/ietf/topics/references.adoc @@ -27,6 +27,10 @@ corresponding online source. However, that data will be fetched not in its nativ XML, as with the rest of Metanorma; a reference to `* [\[[ISO639-2,ISO 639-2]]]` would not be treated any differently. +NOTE: Metanorma will automatically convert references containing other references (with `relation[@type = 'includes']` +into `referencegroup` elements [added in https://github.com/relaton/relaton-ietf/releases/tag/v3.3.1]. That +includes references automatically fetched by Relaton. + That said, any references recognised as being to IETF standards will include the URI for their RFC XML source, and they will be replaced with an `xi:include` link to that URI as an external reference, as is recommended by default for IETF references. That means that the generated RFC XML v3 will still end up referencing @@ -40,7 +44,7 @@ The document identifier is prefixed to the document title, as there is no separa in RFC XML. A reference not auto-fetched from online sources is either a preformatted citation treated as a block, -or else a full citation, entered through AsciiBib. If the citation is preformatted, it is converted +or else a full citation, entered through AsciiBib or bibliographic spans notation. If the citation is preformatted, it is converted to a standalone `reference/title`, with no authors or dates. If the citation is broken down into elements, it is processed as with auto-fetched references: @@ -91,7 +95,6 @@ Who was Dmitri Shostakovich? The USSR's official figurehead composer and son of As of this writing, the following features of RFC XML v3 referencing are not supported: * `displayreference` -* `referencegroup` * Raw RFC XML included in document source, or referenced directly from document source. == Internet draft versions diff --git a/author/iho.adoc b/author/iho.adoc index b2a78799..6b8f0446 100644 --- a/author/iho.adoc +++ b/author/iho.adoc @@ -1,10 +1,10 @@ --- layout: iho-flavor -title: Write IHO documents with Metanorma (alpha) +title: Write IHO documents with Metanorma --- :page-liquid: -You can author any link:https://iho.int/en/iho-publications[IHO publications] deliverable with Metanorma: +You can author the following link:https://iho.int/en/iho-publications[IHO publications] with Metanorma: B-series:: Bathymetric Publications C-series:: Capacity Building Publications @@ -12,8 +12,3 @@ M-series:: Miscellaneous Publications (including Basic Documents) P-series:: Periodic Publications S-series:: Standards and Specifications -{% include flavor-quickstart-steps.adoc flavor=layout.iho_flavor %} - -WARNING: Metanorma-IHO is currently in ALPHA. DO NOT use unless you are prepared to read up on implemented code. -We recommend using `git:master` to minimize issues. - diff --git a/author/iho/authoring-guide/bibliographic-references.adoc b/author/iho/authoring-guide/bibliographic-references.adoc index 7cb585da..346b9b42 100644 --- a/author/iho/authoring-guide/bibliographic-references.adoc +++ b/author/iho/authoring-guide/bibliographic-references.adoc @@ -3,7 +3,7 @@ layout: iho-flavor title: Bibliographic references --- //General Bibliography -//include::/author/topics/sections/entering_bib.adoc[tag=tutorial] +//include::/author/topics/sections/entering-bib.adoc[tag=tutorial] == General diff --git a/author/iho/authoring-guide/block-syntax.adoc b/author/iho/authoring-guide/block-syntax.adoc index c90aa0d1..8b0ee8f4 100644 --- a/author/iho/authoring-guide/block-syntax.adoc +++ b/author/iho/authoring-guide/block-syntax.adoc @@ -149,7 +149,7 @@ Tables are a useful tool to collect and display measured data. As AsciiDoc is al |=== <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. <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. @@ -165,7 +165,7 @@ NOTE: In typical AsciiDoc, `[cols="3"]` is considered a shorthand to `[cols="1,1,1"]`, but this is not supported in Metanorma AsciiDoc. -include::author/iho/topics/markup.adoc[tag=tables-iho] +include::../../../author/iho/topics/markup.adoc[tag=tables-iho] == Images @@ -191,7 +191,7 @@ P:: point of the curve corresponding to a cooking time of stem:[t_90] == Admonitions -Admonitions are signal words used to catch the reader's attention, such as “TIP”, “NOTE”, or “WARNING”. There are two ways to declare an admonition: in a single paragraph and as a block. +Admonitions are signal words used to catch the reader's attention, such as "TIP", "NOTE", or "WARNING". There are two ways to declare an admonition: in a single paragraph and as a block. == Single-paragraph admonitions @@ -309,4 +309,4 @@ required AsciiDoc markup. == Removing auto-numbering from blocks -include::author/iho/topics/markup.adoc[tag=unnumbered-iho] +include::../../../author/topics/document-format/text.adoc[tag=unnumbered] diff --git a/author/iho/authoring-guide/cross-references.adoc b/author/iho/authoring-guide/cross-references.adoc index 8de3f7a0..c201148e 100644 --- a/author/iho/authoring-guide/cross-references.adoc +++ b/author/iho/authoring-guide/cross-references.adoc @@ -12,7 +12,7 @@ The main mechanism for references are anchors and destinations. There are the following types of cross-references: -// * link:/author/topics/sections/entering_bib.adoc[Bibliographic entries] +// * link:/author/topics/sections/entering-bib.adoc[Bibliographic entries] * link:/author/topics/document-format/xrefs[Internal references] * link:/author/topics/document-format/bibliography[Bibliographic entries] * Hyperlinks to external sources (e.g., a link to a website) diff --git a/author/iho/authoring-guide/metadata.adoc b/author/iho/authoring-guide/metadata.adoc index 07d95bcc..df3a3891 100644 --- a/author/iho/authoring-guide/metadata.adoc +++ b/author/iho/authoring-guide/metadata.adoc @@ -345,3 +345,9 @@ This information can be set as follows. <4> STDID for the PDF version. <5> STDID for the printed version. ==== + +== Document history + +include::../../../author/iho/topics/markup.adoc[tag=document-history] + + diff --git a/author/iho/authoring-guide/sections.adoc b/author/iho/authoring-guide/sections.adoc index 81daf462..ceafc043 100644 --- a/author/iho/authoring-guide/sections.adoc +++ b/author/iho/authoring-guide/sections.adoc @@ -21,7 +21,7 @@ Typically, an IHO document contains the following content order: * <> [[preliminary]] -include::author/iho/topics/markup.adoc[tag=preliminary-iho] +include::../../../author/iho/topics/markup.adoc[tag=preliminary-iho] [[terms]] == Terms and definitions diff --git a/author/iho/authoring-guide/terms.adoc b/author/iho/authoring-guide/terms.adoc index 51d9ece5..ccde52a3 100644 --- a/author/iho/authoring-guide/terms.adoc +++ b/author/iho/authoring-guide/terms.adoc @@ -143,4 +143,4 @@ suggested but no clear-cut recommendations are made SOURCE: https://standards.iho.org/wp-content/uploads/import/documents/other/iho_sa_toolkit.pdf[IHO Quick Reference Guide: Standards Development Process] -These levels of requirements are often shown by the use of particular “standards verbs,” i.e., “shall” for requirements, “should” for recommendations, and “may” for guidelines. (more information can be found in the IHO Standards Board Operations Manual and the IHO Standards Style Manual) Figuring out what level of requirement is needed helps determine what kind of document should be developed. +These levels of requirements are often shown by the use of particular "standards verbs," i.e., "shall" for requirements, "should" for recommendations, and "may" for guidelines. (more information can be found in the IHO Standards Board Operations Manual and the IHO Standards Style Manual) Figuring out what level of requirement is needed helps determine what kind of document should be developed. diff --git a/author/iho/authoring-guide/text-formatting.adoc b/author/iho/authoring-guide/text-formatting.adoc index edaf41dc..63b14630 100644 --- a/author/iho/authoring-guide/text-formatting.adoc +++ b/author/iho/authoring-guide/text-formatting.adoc @@ -13,7 +13,7 @@ include::author/topics/inline_markup/footnotes.adoc[tag=tutorial] If IHO produces an Index, include this section, too == Index Terms -include::author/topics/inline_markup/index.adoc[tag=tutorial] +include::author/topics/inline_markup/index_terms.adoc[tag=tutorial] //// // Include 1: inline_markup.adoc @@ -72,20 +72,19 @@ Metanorma extends these simple formats with: //renders as: .Illustration of strikethrough text in Metanorma. -image::/assets/author/topics/document-format/text/fig-strikethrough.png[Illustration of strikethrough text in Metanorma,width=500] - +image::/assets/author/topics/inline_formatting/fig-strikethrough.png[Illustration of strikethrough text in Metanorma,width=500] .Illustration of small caps text in Metanorma. -image::/assets/author/topics/document-format/text/fig-smallcaps.png[Illustration of small caps text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-smallcaps.png[Illustration of small caps text in Metanorma,width=500] .Illustration of underlined text in Metanorma. -image::/assets/author/topics/document-format/text/fig-underline.png[Illustration of underlined text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-underline.png[Illustration of underlined text in Metanorma,width=500] //Include 3: markup.adoc == IHO specific text markup -include::author/iho/topics/markup.adoc[tag=inline-iho] +include::../../../author/iho/topics/markup.adoc[tag=inline-iho] //Include 4: text_formatting.adoc == Character substitutions diff --git a/author/iho/ref/document-attributes.adoc b/author/iho/ref/document-attributes.adoc index 3b393e16..f91aec4d 100644 --- a/author/iho/ref/document-attributes.adoc +++ b/author/iho/ref/document-attributes.adoc @@ -100,6 +100,12 @@ standards and specifications" (2/2007 as amended), 4.2, for the numbering patter ---- ==== +`edition-major`:: The major component of the edition number of the document [added in https://github.com/metanorma/metanorma-iho/releases/tag/v0.7.4]. +If this attribute is present, it is used instead of `edition`, combined with `edition-minor` and `edition-patch` +if they are also present. +`edition-minor`:: The minor component of the edition number of the document [added in https://github.com/metanorma/metanorma-iho/releases/tag/v0.7.4]. +`edition-patch`:: The patch component of the edition number of the document [added in https://github.com/metanorma/metanorma-iho/releases/tag/v0.7.4]. + `:comment-from:`:: The beginning of the period during which comments may be submitted to the document draft. Accepted values: ISO 8601 date. diff --git a/author/iho/topics/markup.adoc b/author/iho/topics/markup.adoc index 7f237d19..d1073365 100644 --- a/author/iho/topics/markup.adoc +++ b/author/iho/topics/markup.adoc @@ -30,7 +30,7 @@ NOTE: This pattern is derived from IHO S-102. * 2 and onwards. Document content. * Annex A onwards. Document content. -tag::preliminary-iho[] +// tag::preliminary-iho[] == Preface segments @@ -104,7 +104,7 @@ Please refer to the full list at the respective committee sites: * https://iho.int/en/ircc[IRCC] -end::preliminary-iho[] +// end::preliminary-iho[] == Overview @@ -156,7 +156,7 @@ title. == Definitions clause -tag::definitions[] +// tag::definitions[] === General @@ -403,6 +403,7 @@ drop with time at constant operating conditions. (Adapted from ISO/IEC ____ ==== +// end::definitions[] == Annexes @@ -470,6 +471,8 @@ is automatically generated by Metanorma. === Tables +tag::tables-iho[] + Table heads and table subheads are marked up as header cells. They are differentiated by line break: [source,asciidoc] @@ -481,6 +484,9 @@ h| Table Row Head + Table Row Subhead | Value ---- +end::tables-iho[] + +// tag::inline-iho[] == Inline === Cross-references @@ -511,3 +517,103 @@ Hello.footnote:abc[This is a footnote] Repetition.footnote:abc[] ---- + +// end::inline-iho[] + + +== Metadata +// tag::document-history[] + +Semantic markup of document history can be added to the document, +link:/author/topics/document-format/meta-attributes#doc-history-misc-container[using Metanorma extension] +and Relaton YAML [added in https://github.com/metanorma/metanorma-iho/releases/tag/v0.9.0]. +The following information is required: + +* The date of the document version. +* The version of the document. +* Description of changes. +* The (personal or corporate) author responsible for the changes. + +The author is expected to be specified with an acronym (or initials, in the case of a person); +Relaton requires a proper name to be specified for contributors, but the `abbreviation` field +should be used alongside it. + +The following illustrates what semantic markup of IHO document history should look like: + +[source, asciidoctor] +----- +[.preface] +== Misc container + +=== document history + +[source,yaml] +---- + - date: + - type: published + value: 2012-04 + edition: 1.0.0 + contributor: + - organization: + name: International Hydrographic Organization + subdivision: Transfer Standard Maintenance and Application Development + abbreviation: TSMAD + amend: + - description: Approved edition of S-102 + - date: + - type: published + value: 2017-03 + edition: 2.0.0 + contributor: + - organization: + name: International Hydrographic Organization + subdivision: S-102 Project Team + abbreviation: S-102PT + amend: + description: > + Updated clause 4.0 and 12.0. + + Populated clause 9.0 and Annex B. + location: + - clause=4.0 + - clause=12.0 + - clause=9.0 + - annex=B + - date: + - type: updated + value: 2017-05 + edition: 2.0.0 + contributor: + - organization: + name: International Hydrographic Organization + subdivision: S-102 Project Team + abbreviation: S-102PT + amend: + description: > + Modified clause 9.0 based on feedback at S-100WG2 meeting. + location: + - clause=9.0 + - date: + - type: updated + value: 2018-02 + edition: 2.0.0 + contributor: + - person: + name: + completename: Cliff Kottman + abbreviation: CK + amend: + description: > + Modified clause 9.0. Deleted contents of Annex B in preparation for updated S-100 Part 10C guidance. Added Annex F: S-102 Dataset Size and Production, Annex G: Gridding Example, Annex H: Statement added for Multi-Resolution Gridding, Annex I: Statement for future S-102 Tiling. + location: + - clause=9.0 + - annex=B + - annex=F + - annex=G + - annex=H + - annex=I +---- + +----- + +// end::document-history[] diff --git a/author/iso/ref/document-attributes.adoc b/author/iso/ref/document-attributes.adoc index 9c7de06e..dffe5df9 100644 --- a/author/iso/ref/document-attributes.adoc +++ b/author/iso/ref/document-attributes.adoc @@ -36,6 +36,13 @@ For ISO 10303-2:2022, the `partnumber` is `2`. For ISO 8000-118, the `partnumber` is `118`. ==== +`:docidentifier:`:: The full document identiifer assembled out of component metadata, +rather than relying on the provided metadata to build it up. + +NOTE: For a committee document, provide the N-document number for this attribute. +The N-document number is normally specified to Metanorma as `:tc-docnumber` for drafts: +see <>. + `:doctype:`:: Has its possible values defined by https://www.iso.org/deliverables-all.html[ISO deliverables: The different types of ISO publications] (mandatory). Permitted types are: @@ -48,6 +55,7 @@ https://www.iso.org/deliverables-all.html[ISO deliverables: The different types `guide`:: Guide (Guide) `technical-corrigendum`::: Technical Corrigendum (Cor) [added in https://github.com/metanorma/isodoc/releases/tag/v1.3.25] `amendment`::: Amendment (Amd) [added in https://github.com/metanorma/isodoc/releases/tag/v1.3.25] +`committee-document`::: Commitee Document (for internal documents) [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.2] `:updates-document-type:`:: (only when `doctype` is set to `amendment` or `technical-corrigendum`) The document type that this amendment or technical corrigendum is @@ -78,7 +86,8 @@ Authors using Metanorma are not expected to edit documents at those stages, and are not necessary in a normal submission process. These stages, however, can be used for mirroring and tracking of final stage and published standards, which many authors do. --- +-- +//Note contains process information. Do not explain process in Ref but link to ISO Flavor page. `:docsubstage:`:: The substage code for the document status (see https://www.iso.org/stage-codes.html[International harmonized stage codes]). @@ -91,6 +100,38 @@ stage "`60`" (published), where a substage of "`60`" is assumed. `true`::: The document is a horizontal standard. `false`::: (default) The document is not a horizontal standard. +`:fast-track:`:: Whether the document is a fast-track standard. [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.0] + +`true`::: The document is a fast-track standard. +`false`::: (default) The document is not a fast-track standard. + +`:document-scheme:`:: Specifies the version of the ISO document specification that should be used in generating +the Metanorma document. [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.1] +Currently used only to specify the PDF layout. ++ +-- +`2024`: The PDF layout as of 2024 (default) +`2013`: The previous PDF layout, published in 2013. +`2012`: The previous PDF layout, published in mid-2012 (1989 with logo change). +`1989` +`1987` +`1972` +`1951`: The first available published ISO format. +-- + +`:semantic-metadata-feedback-link:`:: Specifies the URL for any feedback to be provided for the +ISO standard. [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.1] +Expected for the PDF layout as of 2024, used to generate cover page QR code. + +`:library-ics:`:: The ICS (International Categorization for Standards) number for the standard. +There may be more than one ICS for a document; if so, they should be comma-delimited. + +`:classification:`:: The Universal Decimal Classification for the standard, used instead of the ICS +for legacy presentations of ISO. [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.7.2] +Values are prefixed with `UDC:`. If multiple values are present, the classification token is repeated, +and comma delimited; e.g. `:classification: UDC:563.5.081, UDC:537.71`. Note that UDC uses punctuation symbols, +including colon, but not comma. + === Document identifier ==== General @@ -111,8 +152,9 @@ This is the abbreviation of the publishing organization, typically `ISO` if ISO is the only publisher. If the document is published under co-publishing agreements, it can contain the -abbreviations of other publishing SDOs, delimited by `/` after `ISO`. An `IWA` -document has publisher abbreviation of `IWA`. +abbreviations of other publishing SDOs, delimited by `;` after `ISO`. An `IWA` +document has publisher abbreviation of `IWA`. (These will be rendered with the expected +`/` in the document identifier.) The prefixes occur in the order that they are given in `publisher`. @@ -121,11 +163,11 @@ Attributes: `:publisher:`:: Publisher of the document. Accepted values are: `ISO`::: ISO. -`ISO/IEC`::: Joint ISO and IEC. (e.g. ISO/IEC JTC 1 and ISO/IEC JTC 2 documents) -`IEC/ISO`::: Joint IEC and ISO. (e.g. IEC/ISO SMART documents) -`ISO/IEC/IEEE`::: Joint ISO/IEC/IEEE. -`ISO/IEEE`::: Joint ISO/IEEE. -`ISO/SAE`::: Joint ISO/SAE. +`ISO;IEC`::: Joint ISO and IEC. (e.g. ISO/IEC JTC 1 and ISO/IEC JTC 2 documents) +`IEC;ISO`::: Joint IEC and ISO. (e.g. IEC/ISO SMART documents) +`ISO;IEC;IEEE`::: Joint ISO/IEC/IEEE. +`ISO;IEEE`::: Joint ISO/IEEE. +`ISO;SAE`::: Joint ISO/SAE. `IWA`::: International Workshop Agreement. @@ -371,17 +413,19 @@ depending on where the deliverable gets distributed to (optional). in the drafting stage. `:technical-committee-number:`:: The number of the relevant ISO -technical committee. +technical committee (or equivalent body). -`:technical-committee-type:`:: The type of the relevant technical committee. +`:technical-committee-type:`:: The type of the relevant technical committee or +equivalent body. Typical values are: `TC`::: (default) technical committee `JTC`::: joint technical committee `PC`::: project committee `JPC`::: joint project committee +`Other`::: group not otherwise described (type acronym omitted from rendering) [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.3.4] -`:technical-committee:`:: The name of the relevant ISO technical committee +`:technical-committee:`:: The name of the relevant ISO technical committee or equivalent (mandatory) `:subcommittee-number:`:: The number of the relevant ISO subcommittee. @@ -391,6 +435,7 @@ Typical values are: `SC`::: (default) subcommittee `JSC`::: joint subcommittee +`Other`::: group not otherwise described (type acronym omitted from rendering) [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.3.4] `:subcommittee:`:: The name of the relevant ISO subcommittee. @@ -410,6 +455,7 @@ Typical values are: `CORG`::: co-ordination group `JCG`::: joint co-ordination group `CAG`::: chair advisory group +`Other`::: group not otherwise described (type acronym omitted from rendering) [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.3.4] `:workgroup:`:: The name of the relevant ISO working group. + @@ -521,6 +567,7 @@ For ISO/TC 154/WG 5 "Date and time": ---- ==== +[[distribution-group]] === Distribution group `:tc-docnumber:`:: The document number assigned by a *distribution group* @@ -599,3 +646,10 @@ submission of the stage 40 onwards (DIS/FDIS) documents to ISO editors. [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.2.3]. `false`::: Retain background colors of semantically-annotated spans. + +== Validation + +`:validate-years:`:: If not set, four-digit numbers that could plausibly be years (between 1900 and 2050) +are not warned about. If set, +they are included in validation [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.4.4]. + diff --git a/author/iso/ref/sts-mapping.adoc b/author/iso/ref/sts-mapping.adoc index 6f2d0ff2..f342dccf 100644 --- a/author/iso/ref/sts-mapping.adoc +++ b/author/iso/ref/sts-mapping.adoc @@ -267,7 +267,7 @@ a| `body//sec[array[count(table/col) = 2]]` | a| `definitions` | a| -`body/sec[@sec-type=“scope"]` +`body/sec[@sec-type="scope"]` | *`< >`* | `sections/clause[@type="scope"]` | a| diff --git a/author/iso/topics/content-validation.adoc b/author/iso/topics/content-validation.adoc index b9263223..340e2555 100644 --- a/author/iso/topics/content-validation.adoc +++ b/author/iso/topics/content-validation.adoc @@ -25,7 +25,8 @@ The style rules implemented include: * Numbers with what looks like dots instead of commas for decimal points. (ISO/IEC DIR 2, 9.1) * Groups of numbers without spacing for every three digits. (The gem attempts -to ignore ISO references.) (ISO/IEC DIR 2, 9.1) +to ignore ISO references. The gem also avoids numbers between 1900 and 2050 as potential years, +unless `:validate-years:` is set [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.4.4].) (ISO/IEC DIR 2, 9.1) * No space before percent sign. (ISO/IEC DIR 2, 9.2.1) @@ -72,7 +73,7 @@ scopes.) (ISO/IEC DIR 2, 22.2) * Each clause shall have a title (ISO/IEC DIR 2, 22.2) -* A subclause shall not be created unless there is at least one further subclause at the same level. For example, text in Clause 10 shall not be designated subclause “10.1” unless there is also a subclause “10.2”. (ISO/IEC DIR 2, 22.3.2) +* A subclause shall not be created unless there is at least one further subclause at the same level. For example, text in Clause 10 shall not be designated subclause "10.1" unless there is also a subclause "10.2". (ISO/IEC DIR 2, 22.3.2) * "see" and "refer to" can only introduce informative references. (ISO/IEC DIR 2, 15.5.3) @@ -93,7 +94,8 @@ attention to syntax errors in Metanorma ISO documents. == ISO house style Metanorma also takes the rules in the https://www.iso.org/ISO-house-style.html[ISO house style] -into account [added in https://github.com/metanorma/isodoc/releases/tag/v2.0.5]. +into account [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.0.5], +including 2022 and 2023 updates [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.4.4]. Metanorma now validates against the following requirements: * https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-r-ref_clause3[References in Clause 3 (Terms and definitions)]: @@ -128,4 +130,10 @@ The conjunction _and/or_ should be avoided. Avoid ampersand in ordinary text * https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-p-full[Full stops]: Do not use full stop at the end of a title or caption. - +* https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-need[Need to], +https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-might[might & could]: +Warn of ambiguous provision wording. +* https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-s-quantity[Quantities and units]: +Warn of more than one level of nesting of subscripts. +* https://www.iso.org/ISO-house-style.html#iso-hs-s-text-r-r-ref_unnumbered[Cross-references to an unnumbered document]: +Superscript cross-references must follow punctuation. diff --git a/author/iso/topics/markup.adoc b/author/iso/topics/markup.adoc index f43bdf36..a09e5858 100644 --- a/author/iso/topics/markup.adoc +++ b/author/iso/topics/markup.adoc @@ -110,7 +110,27 @@ spanning multiple-blocks. -- ====== -== Editorial notes +== Notes +=== Units statements +ISO standards, and standards that inherit formatting from them (IEC, BSI), +can have unit statements on their figures and tables, indicating the unit of +measurement used in the tabulated data. Unit statements are entered as +`[NOTE,type=units]`, and are rendered in the top-right corner of the figure or +table [added in https://github.com/metanorma/metanorma-iso/releases/tag/v2.3.6]. + +[source,asciidoctor] +---- +|=== +|Location |Distance + +|Over there | 6 +|=== + +[NOTE,type=units] +Distances in kilometres +---- + +=== Editorial notes Editorial notes can be added to an ISO document, to differentiate feedback from ISO editors to the readers of a circulated draft, from feedback to the authors @@ -285,14 +305,45 @@ any intermediate sections are treated as subclauses. === Term grouping 1 (subclause 1) -==== Term +==== Term A -==== Term +==== Term B === Term grouping 2 (subclause 2) -==== Term +==== Term C +-- + +As a further complication: if there is any text in a term grouping, Metanorma is going +to assume that you intended a systematic term after all. If you want to introduce discursive +text (e.g. boilerplate) in a term grouping, that text has to be flagged the same way +as it would at the start of a terms & definitions section, with a `[.boilerplate]` clause +as discussed in link:/author/topics/document-format/section-terms#overriding-predefined-text[Overriding predefined text]: + +[source,asciidoc] +.Encoding subclause groupings in a terminology clause in mixed order -- +== Terms and definitions + +=== Term grouping 1 (subclause 1) + +[.boilerplate] +==== {blank} +For the purposes of this document, the following terms and definitions apply: + +==== Term A + +==== Term B + +=== Term grouping 2 (subclause 2) + +==== Term C +-- + +Without the `[.boilerplate]` and `=== {blank}`, the "For the purposes of this document" will be assumed +to be the definition of the term "Term grouping 1 (subclause 1)", and Term A and Term B will be assumed +to be its subterms. + === Combined terms and definitions @@ -395,9 +446,9 @@ documents of a committee. Therefore, it does not: * list the documents that use its terminological entries; -* include documents from its committee as “SOURCE”. +* include documents from its committee as "SOURCE". -* It can include documents from another committee as “SOURCE”. +* It can include documents from another committee as "SOURCE". A vocabulary is the only ISO document that can have terminological entries in clauses other than Clause 3. If terminological entries diff --git a/author/itu/ref/document-attributes.adoc b/author/itu/ref/document-attributes.adoc index 7d6f187b..43849998 100644 --- a/author/itu/ref/document-attributes.adoc +++ b/author/itu/ref/document-attributes.adoc @@ -68,6 +68,10 @@ for further details. The identifier for the document, including the series, the document number, and any suffix, but excluding the bureau. For instance, `H.781`, `G.108.2`, `G.709/Y.1331`. +`:td-number:`:: +Temporary Document number for the document [added in https://github.com/metanorma/metanorma-itu/releases/tag/v2.2.5]. +Used for study group meetings. + `:amendment-number:`:: Number of amendment, if this is an amendment [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.2.5]. `:amendment-title:`:: Title of amendment, if this is an amendment [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.2.5]. `:corrigendum-number:`:: Number of corrigendum, if this is a corrigendum [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.2.5]. @@ -294,6 +298,10 @@ In ITU, quotes and apostrophes default to straight. When this attribute is set, Metanorma will convert quotes and apostrophes to smart quotes and smart apostrophes. In the rest of Metanorma, if this attribute is not supplied, quotes and apostrophes default to "`smart`". +`:document-schema:`:: +Used to specify the document scheme that this document aligns to [added in https://github.com/metanorma/metanorma-itu/releases/tag/v2.3.7]. +If the value `legacy` is provided, the resulting behaviour is as with the document attribute `:legacy-do-not-insert-missing-sections:`. + `:legacy-do-not-insert-missing-sections:`:: If set, do not insert the sections "`Scope`", "`References`", "`Definitions`", "`Abbreviations and acronyms`", "`Conventions`" if missing [added in https://github.com/metanorma/metanorma-itu/releases/tag/v1.0.11]. + diff --git a/author/itu/topics/markup.adoc b/author/itu/topics/markup.adoc index 133a9c5a..b30a439d 100644 --- a/author/itu/topics/markup.adoc +++ b/author/itu/topics/markup.adoc @@ -25,6 +25,33 @@ _considering_ ... ---- +If any editors are indicated in the document header, they will be listed +in the preface, before the acknowledgements (if present) or else at the end of +the preface [added in https://github.com/metanorma/metanorma-itu/releases/tag/v2.1.13]: + +[source,asciidoc] +---- +:fullname: Andreas Reis +:affiliation: World Health Organization +:role: editor +:email: reisa@who.int +:fullname_2: Sameer Pujari +:affiliation_2: World Health Organization +:role_2: editor +:email_2: pujaris@who.int +---- + +Renders as: + +____ +|=== +h|Editors: |Andreas Reis | E-mail: pujaris@who.int +| |World Health Organization +| |Sameer Pujari | E-mai: pujaris@who.int +| |World Health Organization +|=== +____ + == Lists The "`ITU Author's Guide`" specifies that ordered lists by default @@ -154,6 +181,16 @@ web site, so that their reference details can be looked up online. That abbrevia can vary from the abbreviation used in documents: e.g. `ITU-T G Suppl. 41`, not (as in the Editing Guidelines) `ITU-T G-Sup.41`. +In order to provide numeric tags for references, as is expected in the bibliography of common text with ISO/IEC, +use user-supplied numeric identifiers: + + +[source,asciidoc] +-- +* [[[b-CMake,(1)b-CMake]]], Kitware (2018), _CMake_. https://cmake.org/. +* [[[ISO20483,(2)ISO 20483]]], _ISO 20483:2013 Cereals and cereal products -- Determination of moisture content -- Reference method_ +-- + == Definitions === Title @@ -226,6 +263,18 @@ e.g. NOTE: This editorial rule is mandated by the ITU Editorial Team, but is not described in the ITU-T Author's Guide. +Table titles and column titles are automatically +capitalised [added in https://github.com/metanorma/isodoc/releases/tag/v2.4.3]. +To prevent this, you will need to set the capitalisation of the initial word to "none", using CSS: + +[source,asciidoc] +---- +.[css text-transform:none]#iPod# specifications +|=== +| Feature | .[css text-transform:none]#iPod# metric +|=== +---- + == Index Indexes are not currently supported in Metanorma for ITU. diff --git a/author/jis.adoc b/author/jis.adoc new file mode 100644 index 00000000..88383d46 --- /dev/null +++ b/author/jis.adoc @@ -0,0 +1,7 @@ +--- +layout: jis-flavor +title: Write JIS documents with Metanorma +--- +:page-liquid: + +{% include flavor-quickstart-steps.adoc flavor=layout.jis_flavor %} diff --git a/author/jis/ref.adoc b/author/jis/ref.adoc new file mode 100644 index 00000000..3b0c797d --- /dev/null +++ b/author/jis/ref.adoc @@ -0,0 +1,4 @@ +--- +layout: jis-flavor +title: Metanorma-JIS reference guides +--- diff --git a/author/jis/ref/document-attributes.adoc b/author/jis/ref/document-attributes.adoc new file mode 100644 index 00000000..88926742 --- /dev/null +++ b/author/jis/ref/document-attributes.adoc @@ -0,0 +1,140 @@ +--- +layout: jis-flavor +--- + += Metanorma JIS document attributes + +[[note_general_doc_ref_doc_attrib_jis]] +[NOTE] +==== +Document attributes listed below are unique to the processing of JIS documents in Metanorma. + +For _common document attributes_, see link:/author/ref/document-attributes/[Document attributes reference] in general Metanorma author's documentation. That page describes attributes that apply to all Metanorma flavors, not just JIS. + +For an _introduction to Metanorma AsciiDoc document attributes_ and how Metanorma uses them, see link:/author/topics/document-format/meta-attributes/[the corresponding topic]. +==== + +== Document information + +`:doctype`:: +Document type. The default is `japanese-industrial-standard`. Supported: ++ +-- +* `japanese-industrial-standard` +* `technical-report` +* `technical-specification` +* `amendment` +* `expert-commentary`. Personal authors are supported for this document type. +-- + +`:title-main-ja:`, `:title-main-en:`:: +Main title of the document, in Japanese or English + +`:title-intro-ja:`, `:title-intro-en:`:: +Introduction to title of the document, in Japanese or English + +`:title-part-ja:`, `:title-part-en:`:: +Part title of the document, in Japanese or English + +`:title-amendment-ja:`, `:title-amendment-en:`:: +Amendment title of the document, in Japanese or English + +`:docnumber:`:: +The number for the document. + +`:partnumber:`:: +The part number for the document. + +`:docseries:`:: +The series for the document. + +`:amendment-number:`:: +The amendment number for the document. + +`:updates:`:: +Identifier of document that this document is an update of. + +`:language:` :: The language of the document (support `en`, `ja`) (default: `ja`) + +`:copyright-year:`:: The year associated with the copyright for the document. + +`:announced-date:`:: The date on which the document was announced in the official gazette (needed for inner cover page boilerplate). +`:revdate:`:: The date on which the document was last updated (needed for inner cover page boilerplate). + +NOTE: Dates are expected to be provided in ISO 8601 format, e.g. 2003-01-13. Dates can be provided in the Japanese calendar, +by appending `-ja` to the attribute name, e.g. `:announced-date-ja: 平成十五年1月13日`. However, without that, Metanorma will +translate Gregorian dates to Japanese calendar dates in Japanese-language documents. + +== Contributor Information + +All the following attributes can be specified multilingually, by adding `-ja` or `-en` after each attribute name +(e.g. `:fullname-en:`, `:investigative-organization-ja_2`) + +`:fullname_{i}:`:: +Name of personal author for this document (for expert commentary) + +`:givenname_{i}:`:: +Given Name of personal author for this document (for expert commentary) + +`:surname_{i}:`:: +Surname of personal author for this document (for expert commentary) + +`:affiliation_{i}:`:: +Name of organization or company for personal author for this document (for expert commentary) + +`:address_{i}:`:: +Address of personal author for this document (for expert commentary) + +`:email_{i}:`:: +Email of personal author for this document (for expert commentary) + +`:role_{i}:`:: +Role of personal author for this document (for expert commentary) (default: `author`) + +`:publisher_{i}:`:: +Publisher for this document (default: `JIS`) + +`:copyright-holder_{i}:`:: +Copyright holder for this document (default: `JIS`) + +`:investigative-organization_{i}`:: +Investigative organization for this document + +`:investigative-committee{i}`:: +Investigative committee for this document. Use only if the chairperson or other representative of the +investigative committee is unknown, otherwise use a personal contributor to specify the representative's +name, role, and position (as the inner cover boilerplate note names the committee representative). +In order to be recognised, the role and role description must be given as below. If a position is not +given (`:contributor-position:`), "chaiperson" will be supplied, in English or Japanese: ++ +-- +.Investigative committee without chairperson +[source,asciidoc] +---- +:investigative-committee: Committee 123 +---- + +.Investigative committee with chairperson +[source,asciidoc] +---- +:fullname_3: MIFUNE Toshiro +:role_3: authorizer +:role-description_3: investigative committee +:affiliation_3: Committee 123 +:contributor-position_3: chairperson +---- + +-- + +`:publisher-abbr_{i}:`:: +Abbreviation of publisher for this document + +`:publisher-logo_{i}:`:: +Logo of publisher for this document (image file) + +`:subdivision_{i}:`` +Subdivision of organization responsible for this document as author and publisher + +`:subdivision-abbr_{i}:`` +Abbreviation of subdivision of organization responsible for this document as author and publisher + diff --git a/author/jis/sample.adoc b/author/jis/sample.adoc new file mode 100644 index 00000000..d4695c63 --- /dev/null +++ b/author/jis/sample.adoc @@ -0,0 +1,25 @@ +--- +layout: jis-flavor +title: "Metanorma JIS samples" +--- +:page-liquid: + +{% include flavor-sample-summary.html flavor=layout.jis_flavor + markup_link="../authoring/" %} + +== Building the sample + +Clone the repository: + +[source,console] +-- +git clone https://github.com/metanorma/mn-samples-jis/ +-- + +Install required gems and build the documents via the provided Makefile from within repository root: + +[source,console] +-- +bundle +make +-- diff --git a/author/jis/topics.adoc b/author/jis/topics.adoc new file mode 100644 index 00000000..ca9445be --- /dev/null +++ b/author/jis/topics.adoc @@ -0,0 +1,4 @@ +--- +layout: jis-flavor +title: Using Metanorma-JIS +--- diff --git a/author/jis/topics/markup.adoc b/author/jis/topics/markup.adoc new file mode 100644 index 00000000..db2dfd1c --- /dev/null +++ b/author/jis/topics/markup.adoc @@ -0,0 +1,17 @@ +--- +layout: jis-flavor +title: Metanorma for JIS markup +--- + +== Sections + +=== Commentary + +Commentary clauses are marked up as annexes with a `commentary` option attribute: + +[source,asciidoc] +---- +[appendix%commentary] +== Commentary +... +---- diff --git a/author/nist.adoc b/author/nist.adoc new file mode 100644 index 00000000..48deee58 --- /dev/null +++ b/author/nist.adoc @@ -0,0 +1,7 @@ +--- +layout: nist-flavor +title: Write NIST documents with Metanorma +--- +:page-liquid: + +{% include flavor-quickstart-steps.adoc flavor=layout.nist_flavor %} diff --git a/author/nist/ref.adoc b/author/nist/ref.adoc new file mode 100644 index 00000000..b948b6a4 --- /dev/null +++ b/author/nist/ref.adoc @@ -0,0 +1,4 @@ +--- +layout: nist-flavor +title: Metanorma-NIST reference guides +--- diff --git a/author/nist/ref/document-attributes.adoc b/author/nist/ref/document-attributes.adoc new file mode 100644 index 00000000..5f0164f1 --- /dev/null +++ b/author/nist/ref/document-attributes.adoc @@ -0,0 +1,406 @@ +--- +layout: nist-flavor +--- + += Metanorma NIST document attributes + +[[note_general_doc_ref_doc_attrib_nist]] +[NOTE] +==== +Document attributes listed below are unique to the processing of IEEE SA documents +in Metanorma. + +For _common document attributes_, see link:/author/ref/document-attributes/[Document attributes reference] in general Metanorma author's documentation. That page describes attributes that apply to all Metanorma flavors, not just IEEE SA. + +For an _introduction to Metanorma AsciiDoc document attributes_ and how Metanorma uses them, see link:/author/topics/document-format/meta-attributes/[the corresponding topic]. +==== + +== Document information + +The general Metanorma document attributes relevant to NIST documents include: + +`:edition:`:: The document version; e.g. `2.0`. + +`:revdate:`:: The date the document was last updated. + +`:copyright-year:`:: The year which will be claimed as when the copyright for +the document was issued. + +`:title-main:`:: The main component of the title of the document +(mandatory). If absent, the first line of the AsciiDoc document, which contains the title +introduced with `=`, is used. + +`:uri:`:: The URI to which this standard is published. + +`:status:`:: Document status/stage. The permitted types are: ++ +-- +* `draft-internal` +* `draft-wip` +* `draft-prelim` +* `draft-public` +* `draft-approval` +* `final` (default: document is published) +* `final-review` +-- + +`:substage:`:: Document substage. Indicates active status of draft or publication. +If a draft or publication is inactive, that is reflected in the coverpage. The +permitted types are: ++ +-- +* `active` (default) +* `retired` (applies only to drafts, when they are abandoned). The `:abandoned-date:` must +be provided, to indicate when the draft was abandoned. +* `withdrawn` (applies to drafts, when when they are superseded by the next draft stage, +and to published documents when they are superseded or no longer valid. +-- + +`:language:`:: +Two-letter code (ISO 639-1) of the language the document is written in. Defaults to `en`. +If multiple languages are used in the document, comma-delimited; e.g. `en,fr`. + + +The following document attributes are specific to NIST: + +`:title-sub:`:: The subtitle of the document. + +`:title-main-short:`:: Shortened form of the title of the document. For use in Word header. +If not provided, `:title-main:` is used. + +`:title-sub-short:`:: Shortened form of The subtitle of the document. For use in Word header. +If not provided, `:title-sub:` is used. + +`:title-document-class:`:: The title of the document class that the document belongs to; +e.g. "Computer Security" for SP 800. + +`:keywords:`:: Comma-delimited list of the keywords associated with the document. + +`:iteration:`:: The iteration of a stage, in case there have been multiple drafts. +Can be a number, or text (e.g. "initial", "final"). + +== Document identifier +The general Metanorma document attributes relevant to NIST documents include: + +`:docnumber:`:: The internal identifier referring to this document. The identifier is a number; +the prefix, e.g. "NIST SP", is supplied by the `:series:` attribute. The NIST identifier is +docnumber-edition (if edition is present) + +`:docidentifier:`:: The document identifier for the document. Normally this should not be supplied, +as the document identifier is composed from the document series, document number, document volume, +and edition/revision (e.g. _NIST SP 800 Revision 1_). + +If the `:docidentifier:` value is provided, it will override this composed value. + +CSWP publications do not have a distinct `:docidentifier:` or `:docnumber:`: they are identified +by their `:issued-date:`. + + + +The following document attributes are specific to NIST: + +`:revision:`:: The document revision; e.g. `1` (Revision 1). Will be stored in Metanorma XML +under the `` tag, with the prefix `Revision `. + +`:version:`:: The document version, when titled as version. Will be stored in Metanorma XML +under the `` tag, with the prefix `Version `. + +`:volume:`:: +The number of the volume of a standard. Is ignored if a precomposed +document identifier (`:docidentifier:`) is supplied. +Is prefixed with "Volume" or "Vol." in display. + +`:part:`:: +The part number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). + +`:section:`:: +The section number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). + +`:supplement:`:: +The supplement number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). +Can be supplied with an empty value to indicate that this is a supplement of a standard. + +`:index:`:: +The index number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). +Can be supplied with an empty value to indicate that this is an index of a standard. + +`:update:`:: +The update number of a standard. Is only used to generate machine readable NIST identifier (nist-mr). + +`:addendum:`:: +The document is an addendum to a document. Used to generate machine readable NIST identifier (nist-mr), +and to style document as addendum. + +`:doi:`:: DOI URL for document (distinct from `:uri:`, which is the URL that NIST +publishes the document under.) + + +== Document series +The following document attributes are specific to NIST: + + +`:series:`:: The publication series that the document belongs to. Legal values are given +as the keys of the +https://github.com/metanorma/pubid-nist/blob/main/series.yaml[pubid-nist series listing] [added in https://github.com/metanorma/metanorma-nist/releases/tag/v2.4.0]. For legacy purposes, `nist-*` is converted to `NIST *` in all caps; and `nist-cswp` +(Cybersecurity White Papers) is converted to the correct `CSRC White Paper`. +`nist-csts` is also supported as an ad hoc series. + +Documents belonging to different series are expected to be rendered differently. As of this +writing, styling has been provided for `nist-cswp` (Cybersecurity White Papers), +`nist-csts` (Cybersecurity Technical Specifications) [added in https://github.com/metanorma/metanorma-nist/releases/tag/v1.2.10], +and for `nist-sp` (SP-800). + +`:series-title:`:: (Added in v1.2.10) +`:series-mrprefix:`:: (Added in v1.2.10) +`:series-abbrev:`:: (Added in v1.2.10) The formal documents published by NIST belong to a registered +list of series, each with a predefined title and abbreviation. Non-formal documents instead belong +to ad hoc series defined for the purposes of Metanorma, such as `nist-csts`. That particular series +acts as an umbrella for user-defined series of publications; so when it is used, the user needs to provide +a title (e.g. "Automated Cryptographic Validation Protocol") and abbreviation (e.g. ACVP) for the user-defined +series. The user also needs to provide the prefix by which the series will be identified in the machine-readable +NIST identifier, when it is at variance with the abbreviation. ++ +-- +In this case, CSTS is retained as the primary series of the publication (and all CSTS documents +are rendered the same way), and ACVP is modelled as a secondary series specific to CSTS. However, +the series information rendered for the document involves the user-defined series, not CSTS itself. +-- + + +== Document dates + +The general Metanorma document attributes relevant to NIST documents include: + +`:issued-date:`:: The date on which the document was authorised to be published. +Referred to within NIST as the "Publication Date". This is the date used on the document +cover page. Only applies to public documents; +drafts instead have a `:circulated-date:` attribute. + +`:published-date:`:: The publication date for the document, when it was physically released. +Referred to within NIST as the "Release Date". This date is not used on the document cover +page; `:issued-date:` is used instead. The Release Date is included in NIST bibliographic metadata. + +`:obsoleted-date:`:: +The date at which a document is considered no longer valid (withdrawn). If a document +is not currently withdrawn (as indicated through `:substage: withdrawn`), +but will be in the future, that is still indicated in the rendering of the document. + +`:confirmed-date:`:: +The date at which a document has been reviewed according to the NIST ERB 5-year review process, +and has been confirmed to be relevant and valid to date. If this attribute is present, +the date is included in the cover page. + +`:updated-date:`:: +The date at which a document has been updated without being considered a distinct new publication. +Used to indicate the date of errata releases. + +`:circulated-date:`:: +The date at which a draft is circulated. Displayed on the cover page of drafts. +MANDATORY FOR DRAFTS. + + + +The following document attributes are specific to NIST: + +`:comment-from:`:: The beginning of the period during which comments may be submitted to the NIST +document draft. ISO-8601 date. + +`:comment-to:`:: The end of the period during which comments may be submitted to the NIST document +draft. The end of the period may change, and may be left open-ended (omitted). ISO-8601 date. + +`:comment-extended:`:: The date on which the during which comments may be submitted to the NIST document +draft was extended. + +`:superseded-date:`:: +The date at which both this document and the document superseding it come into effect, +as a transition period before this document is withdrawn. May be identical to `:obsoleted-date:`, +in which case there is no such transition period. Is indicated in withdrawn publication +cover page; if not provided, the value of `:obsoleted-date:` is given. + +`:abandoned-date:`:: +The date at which work on a document is abandoned. At that date, the document is considered +retired (`substage: retired`). In NIST, only drafts may be retired. If the document +is not currently retired (as indicated through `:substage: retired`), +but will be in the future, that is still indicated in the rendering of the document. + + + +== Document relationships + +The general Metanorma document attributes relevant to NIST documents include: + +`:merges:`:: This document incorporates the document(s) with the nominated +identifiers (semicolon-delimited). + +`:updates:`:: This document is an update of the document(s) with the nominated +identifiers (semicolon-delimited). + +The following document attributes are specific to NIST: + +`:obsoletes:`:: +One or more NIST document that this NIST document standard renders obsolete; implies that the obsoleted +document is withdrawn, and no longer in effect. Comma delimited. +Format is document identifier, e.g. _SP 800-53A Rev. 1_ + +`:obsoleted-by:`:: +One or more corresponding NIST document that this NIST document standard is obsoleted by; requires that +this document is withdrawn, and no longer in effect. Comma delimited. +Format is document identifier, e.g. _SP 800-53A Rev. 1_. +Is the relation between a withdrawn draft, and the next draft in the approval process. + +`:supersedes:`:: +One or more NIST document that this NIST document standard supersedes; the superseded +document may still remain in effect. Comma delimited. +Format is document identifier, e.g. _SP 800-53A Rev. 1_ + +NOTE: The distinction between `obsoletes` and `supersedes` is the withdrawal date of the +original document (`obsoleted-date`); that means that the distinction is predictable given that external information. +The distinction between `obsoleted-by` and `superseded-by`, in the same way, is made by +the withdrawal date of the current document. Relaton does not differentiate between the two relations +for that reason. + +`:superseded-by`:: +One or more corresponding NIST document that this NIST document standard is superseded by; +this document may still remain in effect. Comma delimited. +Format is document identifier, e.g. _SP 800-53A Rev. 1_ +Is *not* the relation between a withdrawn draft, and the next draft in the approval process +(since the earlier draft is automatically no longer in effect). + + +[[document-contributors]] +== Document contributors + + +The general Metanorma document attributes relevant to NIST documents include: + +`:technical-committee:`:: The name of the relevant committee producing the document. + +`:fullname{_i}:`, `:affiliation{_i}:`, `:address{_i}`:: +The full name of a person who is a contributor to the document, +their organization, and the address of that person or organization. +In NIST, only the city is given as the address. +A second person is indicated by using a numeric suffix: `:fullname:`, `:fullname_2:`, `fullname_3:`, &c. +The same convention applies to all the following attributes. + +[[surname]] `:surname{_i}:`:: +The surname of a person who is a contributor to the document. + +[[givenname]] `:givenname{_i}:`:: +The given name(s) of a person who is a contributor to the document. + +`:initials{_i}:`:: +The initials(s) of a person who is a contributor to the document. + +[[role]] `:role{_i}:`:: +The role of a a person who is a contributor to the document. +By default, they are coded as an `editor`; they can also be represented as an `author`. + +`:affiliation{_i}:`:: +The organizational affiliation of a person who is a contributor to the document. + +`:address{_i}:`:: +The organizational address of a person who is a contributor to the document. + +The following document attributes are specific to NIST: + +`:nist-division:`:: Name of NIST division responsible for document. Added to authority +statement as document contact, and to coverage of withdrawn published document. +Default value is "Computer Security Division, Information Technology Laboratory". + +`:nist-division-address`:: Address of NIST division responsible for document. +Added to authority statement as document contact. Use line breaks (in Asciidoctor: +` + \`) if necessary. Default value is +"100 Bureau Drive (Mail Stop 8930) Gaithersburg, MD 20899-8930" + +`:doc-email:`:: Email contact for document + +`:sponsor:`:: +The name of the organization that has sponsored the document, if applicable. The attribute can +contain multiple lines and Metanorma formatting. + +`:sponsor-logo:`:: +The logo of the sponsoring organization, if applicable. + +== Superseding document appearance + +The following document attributes are specific to NIST, and are used to capture details of the document superseding the present document, which populate the present document's coverpage: + +`:superseding-status:`:: Document status/stage of the superseding document, if this document is +superseded or withdrawn. Used for withdrawn drafts. Used for withdrawn published documents, +if an entry for the superseding document is not available on the CSRC website (where it can be +retrieved through the `:obsoleted-by:` document attribute.) + +`:superseding-iteration:`:: The iteration of the stage of the superseding document, +in case there have been multiple drafts. Can be a number, or text (e.g. "initial", "final"). +Used for withdrawn drafts. + +`:superseding-title:`:: The title of the draft document superseding this document. +If not supplied, the current title is assumed to have been retained. Used for withdrawn drafts. +Used for withdrawn published documents, +if an entry for the superseding document is not available on the CSRC website (where it can be +retrieved through the `:obsoleted-by:` document attribute.) + +`:superseding-subtitle:`:: The subtitle of the draft document superseding this document. +If not supplied, the current subtitle is assumed to have been retained. Used for withdrawn drafts. +Used for withdrawn published documents, +if an entry for the superseding document is not available on the CSRC website (where it can be +retrieved through the `:obsoleted-by:` document attribute.) + +`:superseding-circulated-date:`:: +The date at which the draft document superseding this document is circulated. Used for withdrawn drafts. + +`:superseding-issued-date:`:: +The date at which the document superseding this document was authorised to be published. +Used for withdrawn published documents, +if an entry for the superseding document is not available on the CSRC website (where it can be +retrieved through the `:obsoleted-by:` document attribute.) + +`:superseding-doi:`:: +The DOI of the document superseding this document. Used for withdrawn drafts. +Used for withdrawn published documents, +if an entry for the superseding document is not available on the CSRC website (where it can be +retrieved through the `:obsoleted-by:` document attribute.) + +`:superseding-url:`:: +The URL of the document superseding this document. Used for withdrawn drafts. +Used for withdrawn published documents, +if an entry for the superseding document is not available on the CSRC website (where it can be +retrieved through the `:obsoleted-by:` document attribute.) + +`:superseding-authors:`:: +The authors of the superseding document. Comma-delimited. Used for withdrawn published documents, +if an entry for the superseding document is not available on the CSRC website (where it can be +retrieved through the `:obsoleted-by:` document attribute.) + +`:bib-additional-note:`:: Additional note (optional), used on coverpage of withdrawn and retired drafts, and as +"Related Information" on coverpage of withdrawn published documents. + +`:bib-withdrawal-note:`:: Withdrawal note, used on coverpage of withdrawn published documents. + +`:bib-withdrawal-announcement-link:`:: Hyperlink to announcement of withdrawal, used on coverpage of withdrawn published documents. + + +== Visual appearance +The following document attributes are specific to NIST: + +`:call-for-patent-claims:`:: Include the Call for Patent Claims in document drafts, +and the Patent Disclosure Notice in finalised documents. (Not applicable to CSWP.) + +`:commitment-to-licence:`:: Indicate in the Patent Disclosure Notice that +notice and commitment to license have been received. (Not applicable to CSWP.) + +`:patent-contact:`:: Contact for the Call for Patent Claims or Patent Disclosure Notice. +If not supplied, `:doc-email:` is used. (Not applicable to CSWP.) + +`:biblio-as-appendix:`:: By default, bibliographies are treated as separate from appendixes in output: +they are published in front of any appendixes. This is the prescribed behaviour for NIST documents moving +forward. If present, bibliographies are treated in the legacy manner: they are treated like appendixes, +and are given an appendix number according to where in the document they occur. + +`:boilerplate-authority:`:: Nominate a Metanorma XML file encoding the authority statement of the document, +to overwrite the default authority statement included in the gem +(https://github.com/metanorma/metanorma-nist/blob/main/lib/metanorma/nist/nist_intro.xml[`lib/metanorma/nist/nist_intro.xml`], +https://github.com/metanorma/metanorma-nist/blob/main/lib/metanorma/nist/nist_intro_cswp.xml[`lib/asciidoctor/nist/nist_intro_cswp.xml`]), +in case the document is historical, and needs to be generated with a previous authority statement. + + diff --git a/author/nist/topics.adoc b/author/nist/topics.adoc new file mode 100644 index 00000000..64e13a94 --- /dev/null +++ b/author/nist/topics.adoc @@ -0,0 +1,4 @@ +--- +layout: nist-flavor +title: Using Metanorma-NIST +--- diff --git a/author/nist/topics/formats.adoc b/author/nist/topics/formats.adoc new file mode 100644 index 00000000..85713d27 --- /dev/null +++ b/author/nist/topics/formats.adoc @@ -0,0 +1,16 @@ +--- +layout: nist-flavor +title: Metanorma for NIST output formats +--- + +== Metanorma for IEEE output formats + +=== General + +Metanorma for IEEE supports the generation of the following formats. + +`html`:: HTML output +`pdf`:: PDF output +`doc`:: Word document in the `.doc` extension + + diff --git a/author/nist/topics/markup.adoc b/author/nist/topics/markup.adoc new file mode 100644 index 00000000..95b00b66 --- /dev/null +++ b/author/nist/topics/markup.adoc @@ -0,0 +1,408 @@ +--- +layout: nist-flavor +title: Metanorma for NIST markup +--- + +== Introductory material + +=== Document status + +The following table illustrates how transitions between stages of NIST documents are indicated +using `:status:`, `:substage:`, `:iteration:`, and `:confirmed-date`. + +|=== +| ISO stage | NIST | 93 Repeat current phase | 98 Abandon | 99 Proceed + +| 00 Preliminary | `:status: draft-internal` | | (stop work) | `:status: draft-wip`, `:status: draft-public`, or `:status: final` (amend) +| 10 Proposal | `:status: draft-wip` | | `:status: draft-wip`, `:substage: retired` | `:status: draft-wip`, `:substage: withdrawn` or `status: draft-prelim` +| 20 Preparatory | `status: draft-prelim` | | `status: draft-prelim`, `substage: retired` | `status: draft-prelim`, `substage: withdrawn` or `status: draft-public` +| 40 Enquiry | `status: draft-public` | `status: draft-public`, `:iteration: 2`, `:iteration: 3` ... `:iteration: final` | `:status: draft-public`, `:substage: retired` | `:status: draft-public`, `:substage: withdrawn` or `draft-approval` +| 50 Approval | `status: draft-approval` | | `:status: draft-approval`, `:substage: retired` | `:status: final` +| 60 Publication | `:status: final` +| 90 Review | `:status: final-review` | `:status: final`, `:confirmed-date: XXXX-XX-XX` | `:status: final`, `:substage: withdrawn` | `:status: draft-internal` (revise or amend) +| 95 Withdrawal | `:status: final`, `:substage: withdrawn` | | | +|=== + +In the following, parentheses indicate optional attributes. + +* For retired drafts, the following attributes must be provided: `:circulated-date:`, +`:abandoned-date:`, (`:bib-additional-note:`) +* For withdrawn drafts, the following attributes must be provided: `:circulated-date:`, `:obsoleted-date:`, +`:superseding-status:`, (`:superseding-iteration:`), (`:superseding-title:`), +(`:superseding-subtitle:`), `:superseding-circulated-date:`, (`:superseding-doi:`), +(`:superseding-url:`), (`:bib-additional-note:`) +* For withdrawn published documents, the following attributes must be provided: `:issued-date:`, `:obsoleted-date:` (when +the current document is no longer in effect), `:superseded-date:` (when the transition period started, during which both +documents were in effect, if applicable; if not, this has the same value as `:obsoleted-date:`), `:revdate:` (for +when the withdrawal notice was added to the document), (`:bib-additional-note:`) +("Related Information" in the withdrawn document coverpage), `:obsoleted-by:` (giving the superseding document identifier), +`:nist-division:`, (`:bib-withdrawal-note:`), (`:bib-withdrawal-announcement-link:`). If the details +of the superseding document are not available to be retrieved from the CSRC website), the following attributes must +be provided: `:superseding-title:`, (`:superseding-subtitle:`), `:superseding-issued-date:`, `:superseding-status:`, +`:superseding-doi:`, `:superseding-url:`. + +=== Document identifier + +There are three identifiers automatically generated by Metanorma for NIST documents; they +can be overridden by providing a `:docidentifier:` value. + +* The NIST identifier is composed as follows: +** The Abbreviated NIST Series that the document belong to +** The document identifier within the series +** "Volume " followed by the volume number, if present +** A comma, if there is both a volume number and a revision number +** "Revision " followed by the revision number, if present +** The draft abbreviation in parentheses, if present: +*** The iteration number. For public drafts, the first iteration is abbreviated I, the final iteration as F. +For work-in-progress and preliminary drafts, the first iteration is not shown. +*** The abbreviation of the draft stage: WD for Work-In-Progress, PreD for Preliminary, PD for public. +*** So: WD, 2WD, 3WD, FWD; PreD, 2PreD, 3PreD, FPreD; IPD, 2PD, 3PD, FPD +** The update date, in parentheses, MMM dd, yyyy format, if present. The update date is: +*** If the document is published (`:status:` starts with `final`), the date of an errata release (`:update-date:`). +If there is a revision published for the document, that revision is by default now identified by a revision +number, rather than a publication date; but NIST practice varies, and this can be overridden by providing +a full identifier in `:docidentifier:`. +*** If the document is a draft (`:status:` starts with `draft`), the date at which the draft was circulated +(`:circulated-date:`). If `:circulated-date:` is not provided, the date the document was last revised, +`:revdate:`, may be used instead; but document citation assumes that the document is stable enough to be cited +only at the time it is formally released. + + +=== Authority statement + +The authority statement in NIST consists of five sections. They are semantically encoded in Metanorma +XML under the `boilerplate` tag, as subclauses: + +`boilerplate/legal-statement/clause[@id = 'authority1']`:: The initial section of the authority section ("This publication has been developed +by NIST..."). (Not applicable to CSWP.) +`boilerplate/legal-statement/clause[@id = 'authority2']`:: The identifier, revision date, and URL of the document. (Not applicanble to CSWP.) +`boilerplate/legal-statement/clasue[@id = 'authority3']`:: The boxed disclaimer statement ("Any mention of commercial products or reference to commercial organizations...") +`boilerplate/feedback-statement/clause[@id = 'authority4']`:: The public comment period, for drafts +`boilerplate/feedback-statement/clause[@id = 'authority5']`:: The contact details for comments + +The authority statement has been marked up in Metanorma XML rather than Asciidoctor because of its complexity. +If you wish to supply a different authority statement, you will need to provide a piece of Metanorma XML corresponding +to the existing default statement (available from +https://github.com/metanorma/metanorma-nist/blob/main/lib/metanorma/nist/nist_intro.xml[`lib/metanorma/nist/nist_intro.xml`], +https://github.com/metanorma/metanorma-nist/blob/main/lib/metanorma/nist/nist_intro_cswp.xml[`lib/asciidoctor/nist/nist_intro_cswp.xml`]), +and containing +text corresponding to the sections given above. You can give the location of your own authority statement file +relative to the current document through the document attribute `:boilerplate-authority:`. + +=== Author affiliations + +Each author of a NIST document may have their own organizational affiliation, and optionally +a city for that organization. This information is given using the `:fullname:`, `:affiliation:`, +and `:address:` document attributes, with separate organization and address listings for each +author. Metanorma will take care of grouping authors together by organization. + +[source,asciidoctor] +-- +:fullname: Hildegard Ferraiolo +:affiliation: Computer Security Division, Information Technology Laboratory +:fullname_2: Ketan Mehta +:affiliation_2: Computer Security Division, Information Technology Laboratory +:fullname_3: Nabil Ghadiali +:affiliation_3: National Gallery of Art +:address_3: Washington, DC +:fullname_4: Jason Mohler +:affiliation_4: Electrosoft Services, Inc. +:address_4: Reston, Virginia +:fullname_5: Vincent Johnson +:affiliation_5: Electrosoft Services, Inc. +:address_5: Reston, Virginia +:fullname_6: Steven Brady +:affiliation_6: Electrosoft Services, Inc. +:address_6: Reston, Virginia +-- + +Note that the organization location must be given for every author it applies to; rendering will differentiate +between different locations of the same organization. + +=== Preface + +The following sections are automatically moved to the document preface. + +* Foreword +* Abstract +* Keywords (drawn from document attribute, see above) + +In addition, any clause that has the `preface` style attribute is also moved to the document preface, +regardless of where it appears in the source Asciidoctor document. These clauses +appear in the document preface in the order they are given in the source document. +Examples of preface clauses include: + +* Supplemental Content +* Acknowledgements +* Audience +* Document Conventions +* Compliance with NIST Standards and Guidelines +* Conformance Testing +* Note to Reviewers +* Note to Readers +* Trademark Information + +[source,asciidoctor] +-- +[preface] +=== Acknowledgemnts +This section will be moved to the document preface, after the abstract and keywords. +-- + + +Note that any clause titled "Note to Reviewers" will be removed from rendering unless +the document is in draft (has a `:draft:` attribute). + +=== Abstract + +As with all Metanorma gems, Abstracts are recognised as any clause with the style attribute +`[abstract]`. They are rendered in the document preface, under the Metanorma XML tag `abstract`. + +=== Foreword + +As with all Metanorma gems, the foreword is considered to be any text before the first +section title. The foreword is used to capture the introductory statement on the publication +series that precedes the abstract, and its title is entered as a caption: + +[source,asciidoctor] +---- += Document +:title-main: NIST Report +:title-sub: Subtitle of Report + +.Reports on Computer Systems Technology +The Information Technology Laboratory (ITL) at the National Institute +of Standards and Technology (NIST) promotes the U.S. economy and public welfare... +---- + +=== Executive Summary + +This is any section that appears with the role attribute `[.executive-summary]`. +It is rendered after all other preface sections: + +[source,asciidoctor] +---- +[.executive-summary] +== Executive Summary + +This is an executive summary +---- + +=== Errata + +Errata are marked up as an Asciidoctor table with role attribute `[.errata]`. +Errata tables must have a header row containing the headings _Date, Type, Change, Pages_: + +[source, asciidoctor] +---- +[.errata] +|=== +|Date |Type |Change |Page + +|2019-01-01 |Minor |Repaginated |1-12 +|=== +---- + +As an alternative to this markup, semantic markup of document history can be added to the document, +link:/author/topics/document-format/meta-attributes#doc-history-misc-container[using Metanorma extension] +and Relaton YAML [added in https://github.com/metanorma/metanorma-nist/releases/tag/v2.4.0]. +The change type is represented as `amend` classification `type`. The foregoing example would be marked up as follows: + +[source, asciidoctor] +----- +[.preface] +== Misc container + +=== document history + +[source,yaml] +---- +- date: + - type: updated + value: 2019-01-01 + amend: + description: Repaginated + classification: + - tag: type + value: Minor + location: + - page=1-12 +----- + +== Clauses + +=== Terms and definitions + +Glossaries in NIST documents correspond to Terms & Definitions sections elsewhere in +Metanorma. They are appendices in NIST, and any appendix in NIST Metanorma with the +title "Glossary" or "Terminology" is treated as a Terms & Definitions section. + +=== Glossaries + +Glossaries are given as definition lists with role attribute `[.glossary]`: + +[source,asciidoctor] +---- +[.glossary] +stem:[A= {x_1, x_2, ..., x_k}]:: The alphabet, i.e., the set of all possible symbols that a (digitized) noise source produces. +---- + +=== References + +Bibliographies in NIST are contained within annexes: + +[source,asciidoctor] +---- +[appendix] +== References + +LAWS, POLICIES, DIRECTIVES, REGULATIONS, MEMORANDA, STANDARDS, AND GUIDELINES + +[bibliography] +=== Legislation and Executive Orders +* [[[ref1,1]]] E-Government Act [includes FISMA] (P.L. 107-347), December 2002. +---- + +Provided there is only one bibliography in the document, it is automatically titled _References_. + +If an annex contains a single bibliography, then the annex and the bibliography are treated as equivalent: +the bibliography does not have a distinct title. + +== Blocks + +=== Pseudocode + +Pseudocode shall be marked up as an example, with style attribute `[pseudocode]` +(implemented as a macro): + +[source,asciidoctor] +---- +[pseudocode] +==== +_Input: S=(s1,...,sL)_ + +_Output:_ Shuffled _S=(s1,...,sL)_ + +. *for* _i_ *from* _L_ *downto* 1 *do* +.. Generate a random integer _j_ such that 1<=_j_<=_i_ +.. Swap _s~j~_ and _s~i~_ +==== +---- + +Pseudocode will respect initial indentation in paragraph lines, with line breaks: + +[source,asciidoctor] +---- +[pseudocode] +==== + *def* __increment__(x) + + x = x + 1 + + *enddef* +==== +---- + +They will be rendered as figures, but are not included in the count of figures of the document. +(If they must be included, embed them within another figure.) + +=== Recommendations, requirements, and permissions + +Recommendations, requirements, and permissions shall be marked up as examples, +with style attribute "recommendation", "requirement", "permission": + +[source,asciidoctor] +---- +[[recommend63]] +[recommendation] +==== +Because having on-card role and permission information would raise difficult challenges concerning update and revocation, PACS permissions should generally be stored in a PACS facilities-based component, such as a panel or controller database. +==== +---- + +Recommendations, requirements, and permissions are treated like other assets in +text, and automatically numbered and labelled: do not include a "Recommendation" etc. +label with them. + +=== Variables within sourcecode + +Variables within sourcecode are rendered as non-monospace italicised text. To indicate +such variables, `{{{ ... }}}` shall be used as markup within the sourcecode block, +which will be converted to the tag `nistvariable` in Metanorma XML: + +[source,asciidoctor] +--- +[source] +---- + +---- +--- + +In the rest of Metanorma, `{{{ ... }}}` is used to introduce AsciiDoc markup into sourcecode. +In the NIST flavour, this is done through `{{{{ ... }}}}` + +=== Lists + +If an ordered list is intended to describe "steps" within a process, it should start with Arabic numbers and should be encoded with the class `steps`: + +Encoding an ordered list as steps: + +[source, asciidoctor] +---- +[class=steps] +. First Step +. Second Step +. Third Step +---- + + +=== Tables + +For accessibility, NIST authors are expected to insert titles into tables in Word documents as summaries. +The equivalent in Metanorma is to include alt text in any hyperlinks in Asciidoctor, using the `alt` attribute +of tables, as illustrated in the following: + +[source,asciidoctor] +-- +[[table-crossreference-id]] +.Table caption +[alt="Table summary, for use in accessible media"] +|=== +| Head | Head + +| Body | Body +| Body | Body +|=== +-- + +== Inline markup +=== Hyperlinks + +For accessibility, NIST authors are expected to insert tool tips into the hyperlinks they generate in Word documents. +The equivalent in Metanorma is to include alt text in any hyperlinks in Asciidoctor, using the `title` attribute +of hyperlinks, as illustrated in the following: + +[source,asciidoctor] +-- +http://www.example.com[See the example.com link,title=tooltip text] +-- + + +//// +=== Sponsor + +The title page templates cater for at most one sponsoring organization and its logo. If more than one +sponsor is involved, manual intervention will be required on the title page. + +The sponsor logo (`:sponsor-logo:`) is an image file, and it appears on the left hand side of the Word +title page, oppose the NIST logo. The sponsor name (`:sponsor:`) appears underneath the logo. The attribute +can be just the name, or it can be a multi-line attribute, containing Asciidoctor markup. In that case, +it should be entered using Asciidoctor conventions for multi-line document attributes, with `\ +` used for +line breaks: + +[source,asciidoctor] +---- +:sponsor-logo:fema.gif +:sponsor: *Department of Homeland Security* \ + Janet Napolitano, _Secretary_ \ + *Federal Emergency Management Association* \ + Craig Fugate, _Administrator_ \ + *United States Fire Administration* \+ Kelvin J. Cochran, _Assistant Administrator_ +---- +//// + + diff --git a/author/ogc/authoring-guide/bibliographic-references.adoc b/author/ogc/authoring-guide/bibliographic-references.adoc index c02acc1e..a7271555 100644 --- a/author/ogc/authoring-guide/bibliographic-references.adoc +++ b/author/ogc/authoring-guide/bibliographic-references.adoc @@ -3,7 +3,7 @@ layout: ogc-flavor title: Bibliographic references --- //General Bibliography -//include::/author/topics/sections/entering_bib.adoc[tag=tutorial] +//include::/author/topics/sections/entering-bib.adoc[tag=tutorial] == General diff --git a/author/ogc/authoring-guide/block-syntax.adoc b/author/ogc/authoring-guide/block-syntax.adoc index b9c1b5f7..482c895a 100644 --- a/author/ogc/authoring-guide/block-syntax.adoc +++ b/author/ogc/authoring-guide/block-syntax.adoc @@ -149,7 +149,7 @@ Tables are a useful tool to collect and display measured data. As AsciiDoc is al |=== <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. <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. @@ -165,7 +165,7 @@ NOTE: In typical AsciiDoc, `[cols="3"]` is considered a shorthand to `[cols="1,1,1"]`, but this is not supported in Metanorma AsciiDoc. -include::author/ogc/topics/markup.adoc[tag=tables-ogc] +include::../../../author/ogc/topics/markup.adoc[tag=tables-ogc] == Images @@ -191,7 +191,7 @@ P:: point of the curve corresponding to a cooking time of stem:[t_90] == Admonitions -Admonitions are signal words used to catch the reader's attention, such as “TIP”, “NOTE”, or “WARNING”. There are two ways to declare an admonition: in a single paragraph and as a block. +Admonitions are signal words used to catch the reader's attention, such as "TIP", "NOTE", or "WARNING". There are two ways to declare an admonition: in a single paragraph and as a block. == Single-paragraph admonitions @@ -309,7 +309,7 @@ required AsciiDoc markup. == Removing auto-numbering from blocks -include::author/ogc/topics/markup.adoc[tag=unnumbered-ogc] +include::../../../author/ogc/topics/markup.adoc[tag=unnumbered-ogc] == ModSpec requirements diff --git a/author/ogc/authoring-guide/cross-references.adoc b/author/ogc/authoring-guide/cross-references.adoc index 30c10ea3..7513ad65 100644 --- a/author/ogc/authoring-guide/cross-references.adoc +++ b/author/ogc/authoring-guide/cross-references.adoc @@ -12,7 +12,7 @@ The main mechanism for references are anchors and destinations. There are the following types of cross-references: -// * link:/author/topics/sections/entering_bib.adoc[Bibliographic entries] +// * link:/author/topics/sections/entering-bib.adoc[Bibliographic entries] * link:/author/topics/document-format/xrefs[Internal references] * link:/author/topics/document-format/bibliography[Bibliographic entries] * Hyperlinks to external sources (e.g., a link to a website) diff --git a/author/ogc/authoring-guide/metadata.adoc b/author/ogc/authoring-guide/metadata.adoc index 04b80f6f..599470d0 100644 --- a/author/ogc/authoring-guide/metadata.adoc +++ b/author/ogc/authoring-guide/metadata.adoc @@ -255,3 +255,126 @@ ____ This document was prepared by the OGC Architecture Domain Working Group. ____ ==== + +== Document history + +Semantic markup of document history can be added to the document, +link:/author/topics/document-format/meta-attributes#doc-history-misc-container[using Metanorma extension] +and Relaton YAML [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.5.0]. +Document history is realised as a final "Revision history" annex. + +The official structure for document history is as follows: + +Date:: represented as `date`, with type `published`, `updated` (modifications to document), +or `issued` (circulated drafts). +Release:: represented as `edition`, or `version/draft`. +Author:: represented as one or more `contributor` objects, following Relaton YAML. +The role of the contributor can be specified optionally, as `role/type`, to differentiate +editors from the default role of `author`. +Paragraph modified:: represented as `amend/location`, with locality specified as in bibliographic +cross-references; note that `whole` is used in Relaton to specify the entire document (and will be rendered +as "all" in the generated document). +Description:: represented as `amend/description`, can contain inline and block Asciidoc markup. + +The following is an illustration of semantic document history markup for OGC. + +[source, asciidoctor] +-- +[.preface] +== Misc-container + +=== document history + +[source,yaml] +---- +- date: + - type: published + value: 2012-04-02 + version: + draft: Draft + contributor: + person: + name: + completename: R Thakkar + amend: + location: whole + description: Original draft document +- date: + - type: published + value: 2002-08-30 + version: + draft: 0.1 02-077 + contributor: + - person: + name: + completename: Kurt Buehler + role: + type: editor + - person: + name: + completename: George Percivall + role: + type: editor + - person: + name: + completename: Sam Bacharach + role: + type: editor + - person: + name: + completename: Carl Reed + role: + type: editor + - person: + name: + completename: Cliff Kottman + role: + type: editor + - person: + name: + completename: Chuck Heazel + role: + type: editor + - person: + name: + completename: John Davidson + role: + type: editor + - person: + name: + completename: Yaser Bisher + role: + type: editor + - person: + name: + completename: Harry Niedzwiadek + role: + type: editor + - person: + name: + completename: John Evans + role: + type: editor + - person: + name: + completename: Jeffrey Simon + role: + type: editor + amend: + description: Initial version of ORM. Doc OGC +- date: + - type: published + value: 2018-06-04 + version: + draft: 1.0 + contributor: + person: + name: + completename: Gabby Getz + amend: + description: | + * Put _3D Tiles_ specification document into OGC document template + * Miscellaneous updates +---- +-- + diff --git a/author/ogc/authoring-guide/metanorma-adoc.adoc b/author/ogc/authoring-guide/metanorma-adoc.adoc index f007ce07..6ce8f2b6 100644 --- a/author/ogc/authoring-guide/metanorma-adoc.adoc +++ b/author/ogc/authoring-guide/metanorma-adoc.adoc @@ -54,6 +54,8 @@ An OGC document is in the following structure: NOTE: In legacy OGC documents, "`Conformance`" may be section 2, with Normative references and Terms and definitions pushed to 3 and 4 positions. +NOTE: In OGC Engineering Reports, "Submitters" is rendered as "Contributors". + == Automatic numbering in Metanorma // include::/author/concepts/auto_numbering/[tag=auto-num-intro] diff --git a/author/ogc/authoring-guide/sections.adoc b/author/ogc/authoring-guide/sections.adoc index 8c29791b..53832270 100644 --- a/author/ogc/authoring-guide/sections.adoc +++ b/author/ogc/authoring-guide/sections.adoc @@ -21,7 +21,7 @@ Typically, an OGC document contains the following content order: * <> [[preliminary]] -include::author/ogc/topics/markup.adoc[tag=preliminary-ogc] +include::../../../author/ogc/topics/markup.adoc[tag=preliminary-ogc] [[terms]] == Terms and definitions @@ -93,9 +93,9 @@ bibliography section. === Glossary -include::author/ogc/topics/markup.adoc[tag=glossary] +include::../../../author/ogc/topics/markup.adoc[tag=glossary] === Revision history -include::author/ogc/topics/markup.adoc[tag=revision-history] +include::../../../author/ogc/topics/markup.adoc[tag=revision-history] diff --git a/author/ogc/authoring-guide/terms-definitions.adoc b/author/ogc/authoring-guide/terms-definitions.adoc index 97c0bcc7..5411987e 100644 --- a/author/ogc/authoring-guide/terms-definitions.adoc +++ b/author/ogc/authoring-guide/terms-definitions.adoc @@ -60,6 +60,9 @@ this is not allowed. ... ---- +NOTE: The initial notice in Terms and Definitions clauses ("This document uses the terms defned in OGC Policy Directive 49...") +is inserted automatically by Metanorma, and you should not type it in to your document. + == Entering terminology entries @@ -81,7 +84,8 @@ alt:[white rice] <1> {{husked rice}} from which almost all of the bran and embryo have been removed by milling. <2> ---- -<1> `alt:[white rice]` indicates the alternative term for milled rice. +<1> `alt:[white rice]` indicates the alternative term for milled rice. Metanorma uses both the notations `alt:[]` and `admitted:[]`, +and normally refers to this as an admitted term (the terminology of ISO); they mean the same thing. <2> `{{husked rice}}` cites a previously introduced term. @@ -128,4 +132,4 @@ to entry is not included here //OGC specific markup == More OGC terms and definitions -include::author/ogc/topics/markup.adoc[tag=term-def-ogc,leveloffset=-1] +include::../../../author/ogc/topics/markup.adoc[tag=term-def-ogc,leveloffset=-1] diff --git a/author/ogc/authoring-guide/text-formatting.adoc b/author/ogc/authoring-guide/text-formatting.adoc index ec7f9333..628eb85d 100644 --- a/author/ogc/authoring-guide/text-formatting.adoc +++ b/author/ogc/authoring-guide/text-formatting.adoc @@ -13,7 +13,7 @@ include::author/topics/inline_markup/footnotes.adoc[tag=tutorial] If OGC produces an Index, include this section, too == Index Terms -include::author/topics/inline_markup/index.adoc[tag=tutorial] +include::author/topics/inline_markup/index_terms.adoc[tag=tutorial] //// // Include 1: inline_markup.adoc @@ -72,20 +72,20 @@ Metanorma extends these simple formats with: //renders as: .Illustration of strikethrough text in Metanorma. -image::/assets/author/topics/document-format/text/fig-strikethrough.png[Illustration of strikethrough text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-strikethrough.png[Illustration of strikethrough text in Metanorma,width=500] .Illustration of small caps text in Metanorma. -image::/assets/author/topics/document-format/text/fig-smallcaps.png[Illustration of small caps text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-smallcaps.png[Illustration of small caps text in Metanorma,width=500] .Illustration of underlined text in Metanorma. -image::/assets/author/topics/document-format/text/fig-underline.png[Illustration of underlined text in Metanorma,width=500] +image::/assets/author/topics/inline_formatting/fig-underline.png[Illustration of underlined text in Metanorma,width=500] //Include 3: markup.adoc == OGC specific text markup -include::author/ogc/topics/markup.adoc[tag=inline-ogc] +include::../../../author/ogc/topics/markup.adoc[tag=inline-ogc] //Include 4: text_formatting.adoc == Character substitutions diff --git a/author/ogc/authoring.adoc b/author/ogc/authoring.adoc new file mode 100644 index 00000000..6225af06 --- /dev/null +++ b/author/ogc/authoring.adoc @@ -0,0 +1,662 @@ +--- +layout: ogc-flavor +--- + += Writing OGC documents using Metanorma + +== Document type and stage + +[[note_general_doc_ref_doc_attrib_ogc]] +[NOTE] +==== +Document attributes listed below are unique to the processing of OGC documents in Metanorma. + +For _common document attributes_, see link:/author/ref/document-attributes/[Document attributes reference] in general Metanorma author's documentation. That page describes attributes that apply to all Metanorma flavors, not just OGC. + +For an _introduction to Metanorma AsciiDoc document attributes_ and how Metanorma uses them, see link:/author/topics/document-format/meta-attributes/[the corresponding topic]. +==== + +`:abbrev:`:: +The standard abbreviation of the document, used e.g. in URIs + +`:doctype:`:: +*Mandatory.* +Document type. Choices: ++ +-- +* `standard`: Standard (a document subtype is necessary, see <>) (_default_) +* `abstract-specification-topic`: Abstract Specification +* `best-practice`: Best Practice (a document subtype is necessary, see <>) +* `change-request-supporting-document`: Change Request Supporting Document +* `community-practice`: Community Practice +* `community-standard`: Community Standard +* `discussion-paper`: Discussion Paper +* `engineering-report`: Engineering Report +* `other`: Note, Primer, etc. +* `policy`: Policy, Policy -- Name Type Specification +* `reference-model`: Reference Model +* `release-notes`: Release Notes +* `test-suite`: Test Suite +* `user-guide`: User Guide +* `white-paper`: White Paper +-- + +[[ogc-docsubtype]] +`:docsubtype:`:: Document subtype. +Choices: ++ +-- +* For `doctype` set to `standard`: +** `implementation`: Implementation (_default_) +** `conceptual-model`: Conceptual model +** `conceptual-model-and-encoding`: Conceptual model and encoding +** `conceptual-model-and-implementation`: Conceptual model and implementation +** `encoding`: Encoding +** `extension`: Extension +** `profile`: Profile +** `profile-with-extension`: Profile with extension + +* For `doctype` set to `best-practice`: +** `general`: General (_default_) +** `encoding`: Encoding +** `extension`: Extension +** `profile`: Profile +** `profile-with-extension`: Profile with extension +-- + +`:status:`:: +Document status/stage. Synonym: `:docstage:`. +Choices: ++ +-- +* `swg-draft`: SWG Draft. This is the draft created after the TC approval and PC approval votes. +* `oab-review`: OAB Review. This is the intended draft for the "`OAB + OGC-NA Review`". +* `public-rfc`: Public RFC. This is the draft for the (30 days) public comment period. +* `tc-vote`: TC Vote. This is the intended draft for the TC adoption and PC adoption votes. +* `approved`: Published. This is the document intended to be published, after comments are handled with the TC chair (after `tc-vote`). `published` is allowed as a synonym of `approved` [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.5]. +* `deprecated`: Deprecated. This document has been deprecated. +* `retired`: Retired. This document has been retired and no longer considered normative. +-- + +`:edition:`:: +The version number of the document. Dot-delimited, consists of a major version number, a minor version number, +and an optional patch version number; e.g. `2.3.1`: major version 2, minor version 3, patch version 1. + +`:keywords:`:: +Comma-delimited list of the keywords associated with the document. + +[NOTE] +-- +Abbreviations are sometimes used to designate that a document has a +certain document type, document subtype and document stage. +This is a mapping from legacy OGC document values to the current normalized +list: + +"`AS`" Abstract Specification:: Now `:doctype: abstract-specification-topic`. +"`BP`" Best Practice:: Now `:doctype: best-practice`. +"`CAN`" Candidate Standard:: Now `:doctype: standard` and `:docstage: swg-draft`. +"`CC`" Conformance Class:: Not a standalone document, but a part of a document with `:doctype: standard`. No longer exists. +"`CR`" Change Request:: Now `:doctype: change-request-supporting-document`; the actual Change Request is a database entry. +"`CS`" Community Standard:: Now `:doctype: community-standard`. +"`CP`" Community Practice:: Now `:doctype: community-practice`. +"`DP`" Discussion Paper:: Now `:doctype: discussion-paper`. +"`DP-Draft`" Draft Discussion Paper:: Now `:doctype: discussion-paper` with `:docstage: swg-draft`. +"`IPR`" Interoperability Program Report -- Engineering Specification:: Now `:doctype: engineering-report`. +"`IS`" Implementation Standard:: Now `:doctype: standard`, `:docsubtype: implementation`. +"`ISC`" Implementation Standard Corrigendum:: Now `:doctype: standard`, `:docsubtype: implementation` (TBD to indicate `corrigendum`). +"`ISx`" Extension Package Standard:: Now `:doctype: standard`, `:docsubtype: extension`. +"`Notes`" Notes:: Now `:doctype: other`, there is no specific type for "`Notes`". +"`ORM`" OGC Reference Model:: Now `:doctype: reference-model`. +"`PC`" Profile Corrigendum:: Now `:doctype: standard`, `:docsubtype: profile` (TBD to indicate `corrigendum`). +"`PER`" Public Engineering Report:: Now `:doctype: engineering-report`. +"`POL`" Policy:: Now `:doctype: policy`. +"`POL-NTS`" Policy -- Name Type Specification:: Now `:doctype: engineering-report`, there is no specific indication for "`NTS`". +"`Primer`" Primer:: Now `:doctype: other`, there is no specific type for "`Primer`". +"`Profile`" Profile:: Now `:doctype: standard`, `:docsubtype: profile`. +"`RFC`" Request for Comment:: Now `:doctype: standard` and `:docstage: public-rfc`. +"`Retired`" Retired document:: This is a document stage indicated `:docstage: retired`. +"`SAP`" Standard Application Profile:: Now `:doctype: standard`, `:docsubtype: profile`. +"`TS`":: Test Suite (TBD) +"`WhitePaper`" Whitepaper:: Now `:doctype: white-paper`. +-- + +=== Author info + +`:committee:`:: +*Mandatory.* +Name of relevant committee producing the document. Use one of: ++ +-- +* `technical`: Technical Committee +* `planning`: Planning Committee +* `strategic-member-advisory`: Strategic Member Advisory Committee +-- + +`:subcommittee-type:`:: +The type of the relevant subcommittee producing the document. + +`:subcommittee-number:`:: +The number of the relevant subcommittee producing the document. + +`:workingGroup:`:: +*Mandatory.* +Name of relevant working group producing the document. + +`:workgroup-type:`:: +Type of the relevant workgroup producing the document. + +`:workgroup-number:`:: +Number of the relevant workgroup producing the document. + +`:submitting-organizations:`:: +Semicolon-delimited list of the submitting organizations +for this document. The organization names themselves may contain commas. ++ +[example] +-- +EXAMPLE: _University of Calgary, Canada; National Central University, Taiwan_ +-- + +`:editor:`:: +Same as `link:/author/ref/document-attributes/#fullname[:fullname:]` +alongside `link:/author/ref/document-attributes/#role[:role:]` specified as `editor`. + + +=== URIs and IDs + +`:external-id:`:: +External identifier referring to this document. If not supplied, a default value is +generated: `http://www.opengis.net/doc/{abbrevation of doctype}/{abbrev}/{version}`. +(Version is omitted if not provided. If `:abbrev:` and `:doctype:` are not provided, +the default value is not generated. + +`:referenceURLID:`:: +Identifier embedded into a document type-specific external URL. + +`:previous-uri:`:: +URI of previous version of the document. + +`:docnumber:`:: +The document number assigned to the OGC document (without the "`OGC`" prefix). + ++ +The number is formulated following the following rules: ++ +* The final two digits of the year are used at the start of the number (`YY`). +* A three digit number is assigned sequentially for each document in the year (`NNN`). +* The first edition of a document has the document number `YY-NNN`; for example, `00-027` is OGC document 027 first published in 2000. +* Minor editorial changes and corrigenda do not result in a change to the document number +* The `YY-NNN` identifier for a document (the document number root) is maintained if the document undergoes content changes (revisions). These revisions are numbered sequentially, and are indicated with `r` followed by the revision number. So `05-020r27` is revision 27 of OGC document 020 first published in 2005. (Revision 27 may appear years later than 2005.) +* A new major version of a document receives a new document number, including likely a new year. + +=== Mapping to OGC legacy AsciiDoc + +Metanorma-OGC permits legacy OGC AsciiDoc template attributes, +and are treated as synonyms of the corresponding Metanorma attributes: + +|=== +| OGC Metanorma AsciiDoc | OGC legacy AsciiDoc + +| `:copyright-year:` | `:copyrightYear` +| `:workgroup:` | `:workingGroup:` +| `:published-date:` | `:publicationDate:` +| `:issued-date:` | `:approvalDate:` +| `:received-date:` | `:submissionDate:` +| `:docnumber:` | `:docReference:` +| `:fullname:`, with `:role:` = `editor` | `:editor:` +| `:edition:` | `:version:` + +|=== + +== Markup + +=== General + +The rendering of OGC documents has changed over the years. Metanorma formats OGC documents +following current practice: + +* All body text is left justified, with no exceptions allowed. +* Where section obligations are named (i.e. in annex names), they are only given as +"normative" or "informative"; the alternate text of "non-normative" is disallowed. +* Ordered lists follow ISO style numbering, i.e. "a), b), c) ...", with no exceptions allowed. + +=== Inline formatting + +Metanorma-OGC supports highlighting of text [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.16]: + +[source,asciidoc] +---- +This is #text to be highlighted#. +---- + +=== Sections + +The Normative References section may be named just "`References`", reflecting OGC practice. + +=== Preliminary elements + + +==== General + +The following clauses are preliminary elements, and are moved into the frontispiece +of the document (in Metanorma, the document preface). + +The OGC DocTeam has specified that all these elements are *MANDATORY* in OGC documents (in this order): + +* Abstract +* Keywords +* Preface +* Security Considerations [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.5] +* Submitting Organizations +* Submitters + +The Foreword and Introduction are not recognised as part of the document preface +by default [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.2]. + +[NOTE] +-- +Additional preliminary sections are *allowed* but not encouraged. +There are two mechanisms for adding additional content as preliminary elements: + +. Add their content in the <> as additional sub-sections +. Add them as <> +-- + +==== Abstract + +The abstract is recognized as the first clause with an `abstract` style attribute: + +[source,asciidoc] +---- +[abstract] +== Abstract + +This standard describes a conceptual and logical model for the exchange +of groundwater data, as well as a GML/XML encoding with examples. +---- + +==== Preface + +===== General + +The "`Preface`" can be specified in two ways, depending on whether +it is a "`simple clause`", or a "`full clause`". + +===== Simple preface clause + +If the "`Preface`" does not contain subclauses, it is considered +a simple preface clause. + +A simple preface clause is entered as text after the `.Preface` label, +placed between the AsciiDoc document attributes and the first AsciiDoc +section title. It should not be given a section title of its own. + +[source,asciidoc] +---- +:received-date: 2019-01-01 + +.Preface + +Your preface text... + +More preface text... +---- + +[[ogc-full-preface]] +===== Full preface clause + +If the "`Preface`" contains subclauses, it needs to be encoded as +a full preface clause. + +A full preface clause is recognized as a full Metanorma AsciiDoc section, with the +title "`Preface`". Simple preface content can also be encoded this way. +\[added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.1] + +[source,asciidoc] +---- +:received-date: 2019-01-01 + +== Preface + +Your preface text... + +=== Preface sub-clause + +More preface text... +---- + + +==== Keywords + +"`Keywords`" are entered as document attributes as `:keywords:`, with the +value as a comma-delimited list. + +Prefatory text is generated automatically. + +EXAMPLE: + +[source,adoc] +---- +:keywords: ogcdoc, OGC document, groundwater, hydrogeology, GWML2 +---- + +==== Security Considerations + +The Security Considerations section is entered as a clause with the title "`Security Considerations`" + +EXAMPLE: + +[source,adoc] +---- +== Security Considerations + +The following security considerations apply... +---- + +If the Security Considerations are not provided in the source document, the clause is inserted with the text +"`No security considerations have been made for this standard.`" + +==== Submitting Organizations + +"`Submitting Organizations`" are entered using the `:submitting-organizations:` document attribute. +The values are entered using a semi-colon delimited list. + +Prefatory text is generated automatically. + +EXAMPLE: + +[source,adoc] +---- +:submitting-organizations: Geological Survey of Canada (GSC), Canada; U.S. Geological Survey (USGS), United States of America +---- + + +==== Submitters + +"`Submitters`" are entered using a table, contained in a section with the title `Submitters`. + +EXAMPLE: + +[source,adoc] +---- +== Submitters + +|=== +|Name |Affiliation |OGC member + +|Steve Liang | University of Calgary, Canada / SensorUp Inc. | Yes +|=== +---- + +EXAMPLE: + +[source,adoc] +---- +== Submitters + +All questions regarding this submission should be directed to the editor or the submitters: + +|=== +|Name |Affiliation + +|Boyan Brodaric |GSC +|Alexander Kmoch |U Salzburg +|=== +---- + + +[[ogc-additional-prelim]] +==== Additional preliminary elements + +The OGC DocTeam has specified that additional preliminary elements are *allowed* +but not *encouraged*. This is useful for document backwards-compatibility and +cross-published standards at other SDOs. + +Additional preliminary elements should be encoded under the `[.preface]` element, +and they will be rendered *after* the five mandatory preliminary elements. + +Functionality implemented in https://github.com/metanorma/metanorma-ogc/issues/83. + +EXAMPLE: + +[source,adoc] +---- +.Preface + +... + +[.preface] +== Intended audience + +... + +---- + + +=== Examples + +Unlike the normal case in Metanorma, examples can have captions: + +[source,asciidoc] +---- +[example] +.Example caption +==== +Text +==== +---- + +=== Recommendations, requirements, and permissions + +In this clause we will use the term "`requirement`" to refer to the +generic class of recommendations, requirements and permissions. + +NOTE: This subsection supplements +link:/author/topics/document-format/requirements[Requirement, Recommendation, and Permission blocks] +in general Metanorma documentation. + +==== Requirement verifications (tests) + +A requirement with `type=verification` is cross-referenced and captioned as +a "`{Requirement} Test`". It is rendered differently from the +actual requirement itself. + +NOTE: Verifications for Recommendations will be captioned as +Recommendation Tests, similarly for Requirement Tests and +Permission Tests. + +Requirement verifications are excluded from the +"`Table of Requirements`" in Word output +[added in https://github.com/metanorma/metanorma-ogc/releases/tag/v0.2.10]. + +A requirement with `type=abstracttest` is cross-referenced and captioned as +an "Abstract Test", and is otherwise rendered identically to a +Requirement Verification [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.4]. + +==== Requirement classes + +A requirement with `type=class` is cross-referenced and captioned as +a "`{Requirement} Class`", and is rendered differently to the actual +requirement itself +[added in https://github.com/metanorma/metanorma-ogc/releases/tag/v0.2.11]. + +NOTE: Classes for Recommendations will be captioned as +Recommendation Classes, similarly for Requirement Classes and +Permission Classes. + +Requirement Classes must use the following Metanorma Requirement attributes: + +* Target Type. Specified in the `subject` attribute. +* Name. Specified as the requirement's title. +* Dependencies (optional). Specified with the `inherit` attribute (which can take multiple semicolon-delimited values). +* Nesting (optional). Requirements contained in a class are presented as nested requirements. + +A requirement with `type=conformanceclass` is cross-referenced and captioned as +a "Conformance Class", and is otherwise rendered identically to a +Requirement Class [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.4]. + +[example] +======== +[source,asciidoc] +-- +[requirement,type="class",label="http://www.opengis.net/spec/waterml/2.0/req/xsd-xml-rules[*req/core*]",obligation="requirement",subject="Encoding of logical models",inherit="urn:iso:dis:iso:19156:clause:7.2.2;urn:iso:dis:iso:19156:clause:8;http://www.opengis.net/doc/IS/GML/3.2/clause/2.4;O&M Abstract model, OGC 10-004r3, clause D.3.4;http://www.opengis.net/spec/SWE/2.0/req/core/core-concepts-used"] +.GWML2 core logical model +==== + +[requirement,type="general",label="/req/core/encoding"] +====== +====== + +[requirement,type="general",label="/req/core/quantities-uom"] +====== +====== + +[recommendation,type="general",label="/req/core/codelist"] +====== +====== + +[requirement,type="general",label="/req/core/codelistURI"] +====== +====== + +[requirement,type="general",label="/req/core/identifier"] +====== +====== + +[requirement,type="general",label="/req/core/feature"] +====== +====== + +==== +-- +======== + +Embedded requirements (such as are found within Requirement Classes) will automatically +insert cross-references to the non-embedded requirements with the same +label [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.0.8]: + +[source,asciidoc] +-- +[requirement,type="class",label="/req/conceptual"] +.GWML2 core logical model +==== + +[requirement,type="general",label="/req/core/encoding"] +====== +====== + +==== + +[requirement,type="general",label="/req/core/encoding"] +==== +Encoding requirement +==== +-- + +renders as: + +____ +*Requirement Class 3: GWML2 core logical model* + +/req/conceptual + +| Requirement 1: | /req/core/encoding + + +*Requirement 1:* +/req/core/encoding + +Encoding requirement +____ + +==== Rendering requirements + +NOTE: In order to match the Metanorma encoding of requirements to existing OGC +AsciiDoc markup of requirements, users can refer to the rendering of Metanorma +requirements which is aligned the existing, tabular OGC encoding of +requirements. + +An OGC requirement is rendered as follows: + +* It is a table + +* The CSS class of the requirement table is the `type` attribute of the +requirement. ++ +The only types recognised are: + +** `verification`, +** `abstracttest`, +** `class`, +** `conformanceclass`, and +** `recommend` (default). + +* The heading of the table (spanning two columns) is its name (the AsciiDoc role +or style of the requirement, e.g. `[.permission] or [permission]`), optionally +followed by its title (the caption of the requirement, e.g. `.Title`). + +* The title of the table (spanning two columns) is its `label` attribute. + +* The initial rows of the body of the table are: + +** The `obligation` attribute of the requirement, if given: _Obligation_ +followed by the attribute value + +** The `subject` attribute of the requirement, if given: _Target Type_ (for +Class or Conformance Class requirement) or _Subject_, followed by the attribute +value + +** The `inherit` attribute of the requirement, if given: _Dependency_ followed +by the attribute value + +** The `classification` attributes of the requirement, if given: the +classification tag (in capitals), followed by the classification value. + +* The remaining rows of the requirement are the components of the requirement, +encoded as table rows instead of as a definition table (as they are by default +in Metanorma). + +** Components can include nested requirements; these are expected in the class +of Class and Conformance Class requirements. + +** Components can include descriptive text. + +** Components can include open blocks marked with role attributes. ++ +The components recognized are: + +*** `[.specification]` +*** `[.measurement-target]` +*** `[.verification]` +*** `[.import]` +*** Other components are not currently supported. + +==== Legacy Metanorma AsciiDoc syntax + +For legacy reasons, a second Metanorma AsciiDoc syntax is permitted for +recommendations, requirements and permissions. + +In this syntax, Metanorma AsciiDoc tables are used to express the +data needed for requirements: + +* Type of requirement. Specified in the first table cell, + one of `Recommendation`, `Requirement` or `Permission`. + Optionally followed by a number + (which is ignored in parsing; the elements are renumbered + automatically in rendering.) +* Internal label. First paragraph of the second table cell. +* Body of requirement. Second and subsequent paragraphs of the second table cell. + +[example] +==== +[source,asciidoc] +---- +[[recommendation1]] +|=== +|Recommendation |/ogc/recommendation/wfs/2 + + +If the API definition document uses the OpenAPI Specification 3.0, +the document SHOULD conform to the +<>. +|=== +---- +==== + diff --git a/author/ogc/ref/document-attributes.adoc b/author/ogc/ref/document-attributes.adoc index e43b0b00..04b99350 100644 --- a/author/ogc/ref/document-attributes.adoc +++ b/author/ogc/ref/document-attributes.adoc @@ -108,14 +108,16 @@ Choices: * `approved`: Published. This is the document intended to be published. This status is to be set after comments are handled with the TC chair (after `tc-vote`). - `published` is an allowed synonym of `approved`. [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.5] + `published` is an allowed synonym of `approved` [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.5]. * `deprecated`: Deprecated. This document has been deprecated. -* `rescinded`: Rescinded. This document has been rescinded as inaccurate. [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.5.1]. +* `rescinded`: Rescinded. This document has been rescinded as inaccurate [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.5.1]. * `retired`: Retired. This document has been retired and no longer considered normative. +* `legacy`: Legacy. This document has been retired and replaced by a completely new standard [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.4.7]. + [NOTE] The following figure and table shows available document statuses for each document type [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.5.1]. diff --git a/author/ogc/topics/markup.adoc b/author/ogc/topics/markup.adoc index 73e6ca20..6c4cb55b 100644 --- a/author/ogc/topics/markup.adoc +++ b/author/ogc/topics/markup.adoc @@ -440,6 +440,9 @@ Prefatory text is generated automatically. "`Submitters`" are entered using a table, contained in a section with the title "`Submitters`". +NOTE: In OGC Engineering Reports, "Submitters" is rendered as "Contributors". +A title of "Contributors" is treated as equivalent to "Submitters" [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v2.3.14]. + NOTE: Any table included in a Submitters section is automatically unnumbered [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.4.1] diff --git a/author/ref/asciidoc-tips.adoc b/author/ref/asciidoc-tips.adoc index 74b4c78f..87d7db9a 100644 --- a/author/ref/asciidoc-tips.adoc +++ b/author/ref/asciidoc-tips.adoc @@ -1,7 +1,7 @@ --- layout: author-docs --- - +// Rewrite into cheat sheet = Metanorma AsciiDoc tips Metanorma AsciiDoc adopts the Asciidoctor syntax for AsciiDoc, and the diff --git a/author/ref/document-attributes.adoc b/author/ref/document-attributes.adoc index 4e34a6a7..cd85c9b1 100644 --- a/author/ref/document-attributes.adoc +++ b/author/ref/document-attributes.adoc @@ -4,8 +4,7 @@ layout: author-docs = Document attributes -This is the list of link:/author/topics/document-format/meta-attributes[document attributes] -supported by all flavors of Metanorma. +This is the list of document attributes supported by all flavors of Metanorma. [TIP] ==== @@ -107,11 +106,27 @@ Metanorma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/ == Document info -`:publisher:`:: The standards agency publishing the standard; can be multiple -(semicolon-delimited: processed via CSV, recognising quote marks). [added in -https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0]. + +`:publisher_{i}:`:: The standards agency publishing the standard. The first publisher is given as +`:publisher:`; more publishers are added with the suffix `_2`, `_3`, etc., e.g. `:publisher_2:`, +`:publisher_3:` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.0]. + + NOTE: Prior to 1.7.0, this field accepted comma-delimited values [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.1]. ++ +NOTE: Prior to 2.7.0, this field accepted semicolon-delimited values [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0]. +These are processed via CSV, recognising quote marks. This functionality is maintained in later versions, +but other attributes of organisations are ignored (`publisher_logo`, `pub-address`, etc.) + +`:publisher_logo_{i}:`:: The logo of the publisher, specified as an image file; the numbers in the attribute +align to the `:publisher_{i}:` attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.0]. + +`:sponsor_{i}:`:: An organization sponsoring the publication of this document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.0]. ++ +NOTE: If a person needs to be nominated as the responsible party for a sponsoring organization, +that person should be treated as a personal contributor (`:surname_{i}:`, `:affiliation_{i}:`, etc.), +with a `:role:` attribute of `enabler`. + +`:sponsor_logo_{i}:`:: The logo of the sponsoring organization, specified as an image file; the numbers in the attribute +align to the `:sponsor_{i}:` attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.0]. `:copyright-holder:`:: The copyright holder, if distinct from the publisher; can be multiple @@ -125,6 +140,21 @@ The numeric component of the document identifier. The full identifier is formed by prefixing and suffixing this element with other strings derived from metadata. +`:docidentifier:`:: +As an alternative to `docnumber` and other attributes (such as `doctype` and `docstage`), +which form the full identifier by combining multiple attributes, this attribute contains a +full specification of the document identifier and overrides the composition of the document +identifier [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.9]. +This value is used for document identifiers that do not follow normal SDO conventions, +including for documents that are adoptions from other SDOs. + +`:docidentifier-additional:`:: +This attribute provides additional primary identifiers for the document, to be used alongside +the native identifier generated from `docnumber` or `docidentifier` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.2]. +It is intended for copublished standards with multiple primary identifiers. +The list of identifiers is comma-delimited, and is specified as TYPE:VALUE; e.g. +`:docidentifier-additional: IDF:IDF 21, RFC:RFC 97` + `:edition:`:: The document edition. @@ -174,8 +204,9 @@ Comma-delimited list of keywords associated with the document. `:classification:`:: Comma-delimited list of classification tokens, expressed as `type:value` pairs; if no prefix is given to a value, -"default" is supplied as the type [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.1] - +"default" is supplied as the type [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.1]. +There can only be one value per type in a token; if there are multiple classification values of the same type, +repeat the type in a new token; e.g. `:classification: Dewey:563.5.081, Dewey:537.71`. [[draft]] `:draft:`:: The document draft. @@ -207,11 +238,11 @@ value is included in the document attribute: `:semantic-metadata-{name}:`:: Comma-delimited list of values, relating to `name` as semantic metadata about the document. -Stored in the document under `//misc-container/semantic-metadata/{name}`, with repeating tags for each value. +Stored in the document under `//metanorma-extension/semantic-metadata/{name}`, with repeating tags for each value. `:presentation-metadata-{name}:`:: Comma-delimited list of values, relating to `name` as presentation metadata about the document. -Stored in the document under `//misc-container/presentation-metadata/{name}`, with repeating tags for each value. +Stored in the document under `//metanorma-extension/presentation-metadata/{name}`, with repeating tags for each value. [[document-relations]] == Document relations @@ -249,11 +280,15 @@ This document attribute applies to a translated document, pointing to the origin `:doc-uri:`:: The URI to which the DOC representation of this standard is published. `:relaton-uri:`:: The URI to which the Relaton XML representation of this standard is published. +[[timestamps]] == Timestamps [[copyright-year]] `:copyright-year:`:: The year which will be claimed as when the copyright for the document was issued. +`:announced-date:`:: +The date on which the publication of the standard was announced by the issuing authority. + [[issued-date]] `:issued-date:`:: The date on which the standard was issued (authorised for publication by the issuing authority). @@ -269,6 +304,10 @@ The date on which the first version of the standard was created. `:updated-date:`:: The date on which the current version of the standard was updated. +`:corrected-date:`:: +The date on which the current version of the standard was corrected, without that correction amounting to a distinct +update [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.3]. + `:obsoleted-date:`:: The date on which the standard was obsoleted/revoked. @@ -318,9 +357,21 @@ The given name(s) of a person who is a contributor to the document. `:initials{_i}:`:: The initials(s) of a person who is a contributor to the document. +`:contributor-credentials{_i}:`:: +Credentials of the person, appearing after their name in Metanorma flavour-specific +contexts [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.9]. + [[role]] `:role{_i}:`:: -The role of a a person who is a contributor to the document. -By default, they are coded as an `editor`; they can also be represented as an `author`. +The role of a person who is a contributor to the document. +By default, they are coded as an `editor`; they can also be represented as an `author`, +or (if they are the responsible party for a sponsoring organization) `enabler`. +Is meant to draw from the constrained vocabulary of Relaton: `author`, `editor`, `adapter`, +`translator`, `performer`, `realizer`, `publisher`, `distributor`, `owner`, `authorizer`, +`enabler`, `subject`; see https://www.relaton.org/specs/model/creator/[Relaton specification]. + +`:role-description{_i}:`:: +A more detailed description of the role of a person who is a contributor to +the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.5]. `:affiliation{_i}:`:: The organization that a person who is a contributor to the document is affiliated with. @@ -332,7 +383,21 @@ is affiliated with [added in https://github.com/metanorma/metanorma-standoc/rele `:affiliation_subdiv{_i}:`:: The subdivision of the organization that a person who is a contributor to the document is affiliated with [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0]. -Can be multiple (semicolon-delimited: processed via CSV, recognising quote marks). +The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), +and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, +from larger to smaller) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]; +the different hierarchical levels can optionally be prefixed with type and a colon. + +`:affiliation_logo{_i}:`:: +The logo of the organization that a person who is a contributor to the document +is affiliated with, specified as an image file [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.0]. + +`:contributor-credentials{_i}:`:: +The credentials of the person (e.g. "PhD, F.R.Pharm.S"); these are often displayed inline with the +person's name [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.9]. + +`:contributor-position{_i}:`:: +The position of the person within the organization [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.9]. `:address{_i}:`:: The organizational address of a person who is a contributor to the document. @@ -373,14 +438,20 @@ The fax number of a person who is a contributor to the document. `:subdivision:`:: The subdivision of the organization that is responsible for this document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. +The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), +and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, +from larger to smaller) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]; +the different hierarchical levels can optionally be prefixed with type and a colon. `:subdivision-abbr:`:: The abbreviation of the subdivision of the organization that is responsible for this document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. -`:pub-address:`:: +`:pub-address_{i}:`:: The address of the organization responsible for this document, if it overrides -the default. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. + +the default. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. +The number of this and subsequent attributes aligns with the number of +`:publisher_{i}:` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1] + + [NOTE] -- @@ -393,23 +464,54 @@ California + \ United States of America ---- -- ++ +NOTE: As of 2.7.0, if `:publisher:` is semicolon-delimited, instead of using numbered attributes, +this and subsequent publisher attributes are ignored. -`:pub-phone:`:: +`:pub-phone_{i}:`:: The phone number of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. -`:pub-fax:`:: +`:pub-fax_{i}:`:: The fax number of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. -`:pub-email:`:: +`:pub-email_{i}:`:: The email of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. -`:pub-uri:`:: +`:pub-uri_{i}:`:: The URI of the organization responsible for this document, if it overrides the default [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1]. +`:sponsor-address_{i}:`, `:sponsor-phone_{i}:`, `:sponsor-fax_{i}:`, `:sponsor-email_{i}:`, `:sponsor-uri_{i}:`:: +The address, phone number, fax number, email, URI of an organization sponsoring +this document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.0]. + +`:sponsor-subdivision_{i}:`:: +The subdivision of the organization that is sponsoring this document. +The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), +and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, +from larger to smaller) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]; +the different hierarchical levels can optionally be prefixed with type and a colon. + +`:authorizer_{i}:`:: +The organisation that authorised this document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]. + +`:authorizer_logo_{i}:`:: +The logo of the sponsoring organization, specified as an image file; the numbers in the attribute +align to the `:authorizer_{i}:` attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]. + +`:authorizer-address_{i}:`, `:authorizer-phone_{i}:`, `:authorizer-fax_{i}:`, `:authorizer-email_{i}:`, `:authorizer-uri_{i}:`:: +The address, phone number, fax number, email, URI of an organization authorizing +this document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]. + +`:authorizer-subdivision_{i}:`:: +The subdivision of the organization that is authorizing this document. +The subdivisions can be multiple (semicolon-delimited: processed via CSV, recognising quote marks), +and they can also be hierarchical, with multiple levels of subdivision (comma-delimited, +from larger to smaller) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.3]; +the different hierarchical levels can optionally be prefixed with type and a colon. == Visual appearance @@ -621,14 +723,21 @@ https://github.com/pbhogan/sterile/blob/main/lib/sterile/data/smart_format_rules Number of table of contents levels to render. Accepts an integer value. (default: `2`). Can be overridden with output-specific options (`htmltoclevels`, `doctoclevels`). -`:htmltoclevels:`:: +`:toclevels-html:`:: Number of table of contents levels to render in HTML output; used to override `:toclevels:` for HTML output. Accepts an integer value. (default: `2`). +Formerly `:htmltoclevels:` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.5]. -`:doctoclevels:`:: +`:toclevels-doc:`:: Number of table of contents levels to render in Microsoft Word "DOC" output; used to override `:toclevels:` for Word DOC output. Accepts an integer value. (default: `2`). +Formerly `:doctoclevels:` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.5]. + +`:toclevels-pdf:`:: +Number of table of contents levels to render in PDF output; +used to override `:toclevels:` for PDF output [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.5]. +Accepts an integer value. (default: `2`) `:toc-figures:`:: Introduce table of contents for figures [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.4]. @@ -652,17 +761,14 @@ are prefixed with this directory. Accepts a directory path. `:break-up-urls-in-tables:`:: -(for Word output only) If present, long strings in table cells -(longer than 30 characters) are broken up on rendering, to help -tables fit within the page width. -No attribute value needed. [added in -https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.25] + -+ --- -NOTE: Due to limitations of Microsoft Word tables with long string -wrapping, this functionality is only applied to Word output [added in -https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.29]. --- +If present, long strings in table cells are broken up on rendering, to help +tables fit within the page width. No attribute value needed. [added in +https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.25]. +The current behaviour is: strings are broken by zero-width spaces; +words are broken up every 10 characters on punctuation (e.g. URIs on / ), +and every 20 characters if there is no puncutation in the word, +in order to deal with very narrow columns. (Because the break is zero-width, +it will not be visible unless it coincides with the end of a column.) `:suppress-asciimath-dup:`:: By default, MathML in the Metanorma XML has equivalent AsciiMath added @@ -684,6 +790,14 @@ https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4] Final delimiter for markup inserted in sourcecode [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4] +`:source-highlighter:`:: +Whether to use a source highlighter for sourcecode; default value is true [added in +https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2] + +`:source-linenums-option:`:: +Provided a source highlighter is being used, whether to display line numbers; default value is false [added in +https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2] + `:bare:`:: (optional) The document is rendered in "`bare form`" -- without the cover page, @@ -708,6 +822,11 @@ pattern only affects the rendering of cross-references, not the underlying XML representation of the ModSpec instances. See more details at link:/author/topics/document-format/requirements-modspec/#identifier-base[ModSpec identifier base]. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. +`:block-unnumbered:`:: +(optional) +A comma-delimited list of Metanorma block names, which should have numbering +suppressed throughout the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.6]. +Typically will be used for sourcecode fragemnts: `:block-unnumbered: sourcecode`. == PDF protection and permissions diff --git a/author/ref/section_block_attributes.adoc b/author/ref/section_block_attributes.adoc new file mode 100644 index 00000000..a9ccb50a --- /dev/null +++ b/author/ref/section_block_attributes.adoc @@ -0,0 +1,137 @@ +--- +layout: author-docs +title: Clause and block-level attributes +description: An overview of all attributes used on the clause and block levels to influence how Metanorma builds the output. +--- +// To do: Align dumps from existing docs; find a good structure + +// Dump 1 from existing docs (section attributes) += Clause and block-level attributes + +== Language and script + +The language and script of a section is indicated via the optional attributes +`language` and `script`: + +[source,asciidoc] +-- +[language=fr] +== Section 3 + +[appendix,script=Zmth] +== Math Appendix +-- + +== Obligations + +The obligation of a section -- whether it is normative or informative -- is indicated +via the attribute `obligation` (see example below). + +For most sections, this is fixed; for annexes and clauses, +the default value of the obligation is "normative" and users need to set the obligation +to "informative" as a section attribute if needed. For example: + +[source,asciidoc] +-- +[[AnnexA]] +[appendix,obligation=informative] +== Determination of defects +-- + +== Numbering + +As with link:/author/topics/document-format/text#numbering-override[block element numbering], +a clause number may be provided to override auto-numbering. + +For instance, in order to number out-of-sequence clauses in updated +documents or amendments [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.3]. + +A manual clause number is specified with the attribute `number`: + +[source,asciidoc] +---- +== Clause 7 + +[number=0] +=== Zeroth Subclause +---- + +Elements subsequent to the manually numbered element will be auto-numbered +so as to follow the previous element. This may include incrementing the final +letter in an alphanumeric clause number (e.g. _7a_ followed by _7b_.) + +If resumption of auto-numbering is not intended for subsequent clauses +(e.g. _7bis_ should not be followed by _7bit_), +an explicit number also needs to be given to those clauses separately. + + +== Inline headings + +Inline subclause headings (e.g. for test methods) are indicated by preceding the heading +with the `[%inline-header]` option attribute. So in the Rice Model document, + +[source,asciidoc] +-- +[%inline-header] +==== Sieve, + +with round perforations of diameter 1,4 mm. +-- + +renders as + +____ +*A.2.1.1. Sieve,* with round perforations of diameter 1,4 mm. +____ + +// Dump 2 from existing docs + + +== Paragraph alignment + +Paragraph alignment is defined as the `align` attribute for paragraphs. + +[example] +.Examples of possible paragraph alignments +==== +[source,asciidoc] +-- +[align=left] +This paragraph is aligned left + +[align=center] +This paragraph is aligned center + +[align=right] +This paragraph is aligned right + +[align=justified] +This paragraph is justified, which is the default +-- + +renders: + +image::/assets/author/topics/document-format/text/fig-par-align.png[Illustration of possible paragraph alignments] +==== + +If the paragraph contains line breaks, and the default alignment in the +stylesheet is justified (as is often the case in Word output), it is necessary +to specify `[align=left]` to make the paragraph look as normally expected. + +[example] +.Example of a paragraph containing line breaks that needs to be left-aligned +==== +[source,asciidoc] +-- +[align=left] +Vache Equipment + +Fictitious + +World + +mailto:gehf@vacheequipment.fic[] +-- + +renders: + +image::/assets/author/topics/document-format/text/fig-left-aligned.png[Illustration of left-alignment for multiple line-breaks] +==== + diff --git a/author/topics/automation/extraction_from_mn.adoc b/author/topics/automation/extraction_from_mn.adoc new file mode 100644 index 00000000..c3ffcaff --- /dev/null +++ b/author/topics/automation/extraction_from_mn.adoc @@ -0,0 +1,33 @@ +--- +layout: author-docs +title: Extracting content from Metanorma +--- +== Extracting content from Metanorma + +=== General + +Images, source code, and requirements can all be extracted out of the +generated Metanorma XML downstream, by the `metanorma -e` command. + +=== Specifying filenames + +By default, the filename for each extracted snippet is automatically +generated. (Extraction only applies to data-uri encoded images, +which no longer preserve their filename.) + +The attribute `filename` on images, source code, and requirements +gives the filename that any inline-encoded +images, source code, and requirements should be +exported to, if that is requested by downstream tools. + +[source,asciidoc] +-- +[filename="image1.gif"] +image::logo.gif +-- + +In this instance, the image is read in from `logo.gif`, but is converted in the +XML output to a data-uri encoding. The encoding will have the filename attribute +of `image1.gif`; that instructs any downstream processing that extracts images +out of the file (such as `metanorma -e`) to extract this image to the file `image1.gif`, +instead of using an automatically generated filename. diff --git a/author/topics/blocks.adoc b/author/topics/blocks.adoc new file mode 100644 index 00000000..4a9d0843 --- /dev/null +++ b/author/topics/blocks.adoc @@ -0,0 +1,47 @@ +--- +layout: author-docs +--- += Blocks + +tag::tutorial[] +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. + +.Examples for different blocks +[source, AsciiDoc] +------ +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 +. I'm list item number three + +//// <2> +I'm a comment. +//// + +[source, python] <3> +---- +print("Hello World!") +---- +------ + +<1> Paragraphs and lists are types of blocks that do not need any delimiters. They are separated by a blank line in between blocks. +<2> Comments use four slashes as a delimiter `////`. No other block uses slashes to begin and end a block. +<3> All other types of blocks rely on delimiters, such as four dashes `----` or four equal signs `====`. This block contains a code sample written in python. + + +There are many types of blocks in AsciiDoc, such as: +* Paragraphs +* Lists +* Tables +* Images +* Admonitions (Note, Caution, Warning, etc.) +* Examples +* Code samples +* Mathematic formulas +* Term definitions +* Comments +* Reviewer Notes + +end::tutorial[] \ No newline at end of file diff --git a/author/topics/blocks/admonitions.adoc b/author/topics/blocks/admonitions.adoc new file mode 100644 index 00000000..cbaa42a5 --- /dev/null +++ b/author/topics/blocks/admonitions.adoc @@ -0,0 +1,289 @@ +--- +layout: author-docs +title: Admonitions +--- +tag::tutorial[] + +== General + +Admonition blocks are typically inserted into the main content of a document +providing guidance or request readers to exercise caution. + +== Types of admonitions + +Metanorma supports the following admonition types: + +NOTE:: Informative guidance. +TIP:: Useful information. +EDITOR:: Editor's notes that will appear in a draft document. +IMPORTANT:: Important information on the application of the document. +WARNING:: Information that includes safety concerns. +CAUTION:: Information that the reader must be aware. +TODO:: Author's or editor's internal notes, not rendered. + +The following types of admonitions require an atypical syntax for access: + +DANGER:: Information that can lead to safety concerns if not covered. +SAFETY PRECAUTION:: Information that relates to safety precautions. + +NOTE: Typical AsciiDoc only supports NOTE, TIP, IMPORTANT and WARNING. + + +== Specifying admonitions + +There are two ways to declare an admonition: in a single paragraph and as a block. + + +=== Single paragraph admonitions + +Start a new line with the admonition type in all caps and a colon and write your +admonition. + +.Example for a single paragraph note +[source,adoc] +---- +NOTE: Advice on when to use which admonition type is specified in ANSI Z535.6. +---- + +=== Block admonitions + +The syntax for a block admonition is as follows. + +[source,adoc] +---- +[NOTE] <1> +==== <2> +Content of the admonition block. <3> + +Unlike an admonition paragraph, it may contain any AsciiDoc content. +==== <4> +---- +<1> Admonition type in all caps enclosed in square brackets +<2> Block start delimiter with 4 `=` signs. +<3> Multi-paragraph admonition content. +<4> Block end delimiter with 4 `=` signs. + + +.Example of specifying other types of admonitions +====== +[source,asciidoc] +---- +== General requirements + +[NOTE] +==== +This is just a note providing guidance. +==== + +[IMPORTANT] +==== +This is an important message. +==== + +== Safety requirements + +[WARNING] +==== +This important notice applies to safety concerns. +==== + +[CAUTION] +==== +This notice must not be ignored. +==== +---- +====== + +end::tutorial[] + +=== Specifying DANGER and SAFETY + +If the admonitions "`Danger`" and "`Safety Precaution`" are needed, they should +be indicated through a `type` attribute, which will override the admonition type +appearing. + +[example] +.Example of specifying Danger and Safety Precaution messages +====== +[source,adoc] +-- +[type=Danger] +CAUTION: Do not perform maintenance tasks while the machine is still operating. + +[WARNING,type=Safety Precaution] +==== +This is a safety precaution + +spanning multiple-blocks. +==== +-- +====== + + +=== Folding notes + +==== General + +Notes that are not at the end of a clause are folded into the preceding block, +if that block is not delimited (so that the user could not choose to include or exclude a note). + +That is, notes immediately following these block types are automatically folded +into the preceding element: + +* list +* formula +* figure +* table + + +==== Prevent folding + +To prevent a note from folding into the preceding block, add the attribute +`keep-separate` to the +note [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.29]. + +NOTE: Extended to apply to tables [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6]. + +[source,asciidoc] +-- +* A +* B +* C + +[NOTE,keep-separate=true] +==== +Note not folded into its preceding block +==== +-- + +Without the `keep-separate=true` markup, the note would be attached to the list, +and numbered accordingly. + + +[source,asciidoc] +-- +[NOTE] +This note will be folded in the preceding block. + +NOTE: This one too. +-- + +Notes may be given a type through the attribute +`type` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1]. + +[source,asciidoc] +-- +[NOTE,type=bibliographic] +==== +Bibliographic note +==== +-- + + + +=== Whole document admonitions + +Admonitions ("`NOTE`", "`IMPORTANT`", "`WARNING`", "`CAUTION`" etc.) +in the document body (i.e. within a main body clause) can be +stated to apply to the entire document by moving them to the +start of the document body, before the main sequence of clauses. + +This can be done by giving them the attribute +`beforeclauses=true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.30]. + +[source,asciidoc] +---- +== Scope + +[IMPORTANT,beforeclauses=true] +==== +This important notice applies to the entire document. +==== + +My scope text... +---- + + +=== Preface admonitions + +Admonitions in the document prefaces (including in the Foreword) can be stated +to apply to the entire preface by moving them to the start of the preface, +before the Foreword. This can be done by giving them the same attribute +`beforeclauses=true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.2]. + +[source,asciidoc] +---- += Document title +:document-attribute: XXXX + +[IMPORTANT,beforeclauses=true] +==== +This important notice applies to the entire document. +==== + +== Foreword + +My foreword text... +---- + +=== Cover page admonitions + +An admonition in the document prefaces can instead be flagged to be rendered on +the cover page of the document, through +`coverpage=true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.8]. + +[source,asciidoc] +---- += Document title +:document-attribute: XXXX + +[IMPORTANT,coverpage=true] +==== +This important notice appears on the cover page. +==== + +== Foreword + +My foreword text... +---- + +Normally, the label of the type of admonition (_NOTE_, _IMPORTANT_, etc) is +inserted at the start of the admonition in rendering. This may not be desirable, +especially for coverpage admonitions. + +Inserting the admonition type is suppressed through +`notag=true` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.8]. + +[source,asciidoc] +---- += Document title +:document-attribute: XXXX + +[IMPORTANT,coverpage=true,notag=true] +==== +This important notice appears on the cover page. +==== + +== Foreword + +My foreword text... +---- + + +=== Explicitly-defined terminology entry notes + +Normally, notes are only tagged as term notes when they appear in the context of a terms section. + +Rarely, term notes need to be presented in isolation, including in ISO Amendments or +Technical Corrigenda. + +To achieve that, mark the note up with +`%termnote` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2]. + +[source,asciidoc] +-- +[NOTE%termnote] +==== +Bibliographic note +==== +-- diff --git a/author/topics/document-format/annotations.adoc b/author/topics/blocks/annotations.adoc similarity index 98% rename from author/topics/document-format/annotations.adoc rename to author/topics/blocks/annotations.adoc index f44c2fc3..349e29ea 100644 --- a/author/topics/document-format/annotations.adoc +++ b/author/topics/blocks/annotations.adoc @@ -134,6 +134,7 @@ The `from`, `to` `reviewer` and `date` attributes are optional and may be specified. +[[reviewer]] == Reviewer notes === General @@ -182,7 +183,8 @@ of where the reviewer note should appear (standalone) or end (ranged). In the case of a standalone note, either do not specify a `to`, or ensure that the `to` is set to the same anchor as the `from`. - +** `type` is a classification of the reviewer note, which may be used in downstream +processing [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.1]. [[standalone]] === Standalone reviewer note diff --git a/author/topics/document-format/diagrams.adoc b/author/topics/blocks/diagrams.adoc similarity index 99% rename from author/topics/document-format/diagrams.adoc rename to author/topics/blocks/diagrams.adoc index 45da92e3..7eda640f 100644 --- a/author/topics/document-format/diagrams.adoc +++ b/author/topics/blocks/diagrams.adoc @@ -71,3 +71,4 @@ a `plantuml` directory relative to the current path. * Visit the https://plantuml.com/[PlantUML website] to learn more about PlantUML and what kinds of diagrams it supports. + diff --git a/author/topics/blocks/figures.adoc b/author/topics/blocks/figures.adoc new file mode 100644 index 00000000..1eb650f3 --- /dev/null +++ b/author/topics/blocks/figures.adoc @@ -0,0 +1,159 @@ +--- +layout: author-docs +title: Figures +--- + +== Figures + +=== General + +In standardization documents, figures are used as document elements to present +non-textual material so that they are independently referable. + +In Metanorma, the usage of the `image` command will result in a figure. +Please refer to link:/author/topics/blocks/images[images] for details +of the `image` command. + + + +=== Key + +Like formulae, figures can be followed by a definition list for the variables used in the figure. +This definition list is marked up with `[%key]` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3]. + +The syntax is as follows: + +[source,asciidoc] +-- +[[some-anchor]] <1> +.Figure title <2> +image::figure-path.png[] <3> + +[%key] <4> +{some-id}:: {some-description} <5> +-- +<1> Optional anchor for referencing +<2> Title of the figure +<3> The image command with path +<4> Specification of figure key section +<5> Key entry: `{some-description}` is text that describes information about the thing +represented by `{some-id}` + + +[example] +.Example of providing a key for a figure (ISO Rice document) +==== +[source,asciidoc] +-- +.Typical gelatinization curve +image::rice_images/rice_image2.png[] +footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.] + +[%key] +stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent +stem:[t]:: cooking time, expressed in minutes +stem:[t_90]:: time required to gelatinize 90 % of the kernels +P:: point of the curve corresponding to a cooking time of stem:[t_90] + +NOTE: These results are based on a study carried out on three different types of kernel. +-- +==== + +The key definition list can also be preceded by a paragraph consisting of +`\*Key*`, though that is not recommended. + +[example] +.Example of providing a key for a figure using the `\*Key*` syntax (ISO Rice document) +==== +[source,asciidoc] +---- +.Typical gelatinization curve +image::rice_images/rice_image2.png[alt text] +footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.] + +*Key* + +stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent +stem:[t]:: cooking time, expressed in minutes +stem:[t_90]:: time required to gelatinize 90 % of the kernels +P:: point of the curve corresponding to a cooking time of stem:[t_90] + +NOTE: These results are based on a study carried out on three different types of kernel. +---- +==== + + + +=== Discursive figures + +A discursive figure, containing text as well as images, can be marked up as an +example, with a `[.figure]` role [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.7]: + +[source,asciidoc] +-- +[.figure] +.Typical gelatinization curve +==== +image::rice_images/rice_image2.png[alt text] + +This is lots of discursive text +==== +-- + + +=== Subfigures + +Subfigures (which appear in ISO formats, for example) are entered by including +images in an example block. + +[source,asciidoc] +-- +.Stages of gelatinization +==== +.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels) +image::rice_images/rice_image3_1.png[] + +.Intermediate stages: Some fully gelatinized kernels are visible +image::rice_images/rice_image3_2.png[] + +.Final stages: All kernels are fully gelatinized +image::rice_images/rice_image3_3.png[] +==== +-- + + + +=== Preformatted blocks + +Figures can include preformatted blocks, as well as images. + +For accessibility, preformatted blocks can be provided with an `alt` text +attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10]. + +[sources,asciidoc] +-- +[alt=ASCII art of a dog] +.... + ___^_ + / | \__/\ + \ / ^ ^| + / \_/ 0 0_ + / \ + / ___ 0 | +/ / \___ _/ +.... +-- + +=== Figure classes + +Figures in documents can belong to different classes (e.g. _Plate_, _Chart_, _Diagram_), +each of which can be auto-numbered and captioned differently. In order to achieve this, +the desired class can be indicated +through the `class` attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.5]. + +[source,asciidoc] +-- +[class=plate] +.Rice husk separation in rice farm at Breton near Dinan +image::logo.jpg[] +-- \ No newline at end of file diff --git a/author/topics/document-format/forms.adoc b/author/topics/blocks/forms.adoc similarity index 98% rename from author/topics/document-format/forms.adoc rename to author/topics/blocks/forms.adoc index ced01373..4ed56824 100644 --- a/author/topics/document-format/forms.adoc +++ b/author/topics/blocks/forms.adoc @@ -1,10 +1,10 @@ --- layout: author-docs +title: Forms --- - = Forms -Metanorma supports a subset of HTML form elements, encoded using Asciidoctor +Metanorma supports a subset of HTML form elements, encoded using Asciidoctor macros [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.2]. In PDF and Word output, these elements are rendered with simple fallbacks. @@ -15,7 +15,7 @@ input `type` attribute, and attributes are the remaining supported attributes (`id name value disabled readonly checked maxlength minlength`), as comma-delimited `name=value` expressions. The supported types of input are `button checkbox date file password radio submit text`. * A `label` element is entered as the macro `label:for:[text]`, where `for` is the value of the -label `for` attribute (i.e. the `id` attribute of the element it references), and `text` is the +label `for` attribute (i.e. the `id` attribute of the element it references), and `text` is the textual content of the label. * A `select` element is entered as the macro `select:[attributes]`, where `attributes` are the supported `select` attributes (`id name size disabled multiple value`). The `select` element @@ -24,7 +24,7 @@ option, and `attributes` are the supported `option` attributes (`disabled value`). For consistency with `input`, the `select/@value` is used to indicate a preselected value, instead of `option/@selected`. * A `textarea` element is entered as the macro `textarea:[attributes]`, where `attributes` are -the supported `textarea` attributes (`id name rows cols value`). For consistency with `input`, +the supported `textarea` attributes (`id name rows cols value`). For consistency with `input`, the `textarea/@value` is used to indicate a prepopulated value, instead of text content for the `textarea`. diff --git a/author/topics/blocks/images.adoc b/author/topics/blocks/images.adoc new file mode 100644 index 00000000..60ceb678 --- /dev/null +++ b/author/topics/blocks/images.adoc @@ -0,0 +1,206 @@ +--- +layout: author-docs +title: Images +--- + +== Images + +=== General + +The inclusion of images in Metanorma AsciiDoc is through the `image` command. + +Metanorma AsciiDoc supports most of the features of `image` defined in Asciidoctor AsciiDoc. +For more information, please refer to the typical `image` command attributes available at: +https://docs.asciidoctor.org/asciidoc/latest/macros/images/[Asciidoctor]. + +There are two types of AsciiDoc images, block and inline. + +=== Block image +tag::tutorial[] + +A block image is displayed as a discrete element, i.e., on its own line, in a document. + +The syntax used to enter a block image is as follows. +The `image::` line is preceded by a blank line, entered on a line by itself, +and then followed by a blank line. + +[source,adoc] +---- +image::{PATH}[] +---- + +Where `PATH` is the image path. + +In Metanorma, block images are always entered as a figure. Please refer to the +link:/author/topics/blocks/figures[Figures] documentation. + +[source, AsciiDoc] +---- +[[my-anchor]] <1> +.Title for image <2> +image::images/path.png[Alt text] <3> +---- +<1> Optional anchor for referencing +<2> Image title +<3> Image command with path and optional alt text. If no alt text is provided, leave the square brackets at the end empty (`image::path[]`). + +end::tutorial[] + + +=== Inline image + +An inline image is displayed in the flow of another element, such as a paragraph. + +This is useful when you want to incorporate buttons or other icons into the text flow. + + +=== Data URIs + +Metanorma allows https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs[Data URIs] as the URL for an image: + +[source,asciidoc] +-- +image::data:image/png;base64,ivBO...[alt text] +-- + +NOTE: Data URIs are not typically supported by AsciiDoc processors. + + +=== Image directory location + +The root path for all `image` paths can be defined at the document-level, +through the document attribute `:imagesdir:`. + +[source,adoc] +---- += Document title +:imagesdir: my-images/ <1> + +... +image::myimage01.png[] <2> +---- +<1> The document attribute `:imagesdir:` will set all root paths of the `image` command to the specified path. +<2> The reference to `myimage01.png` is joined with the path set at `:imagesdir:`, which results to +`my-images/myimage01.png`. + +More details of the `:imagesdir:` attribute can be found at +https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/[AsciiDoc documentation]. + + +=== Attributes + +==== Image size + +The size of an image can be modified via the `height` and `width` attributes. + +By default, both `height` and `width` are set to the value `auto`, which means +that the image will be shown according to the best visual settings determined +by Metanorma. + +Image dimensions can also be fixed with pixel values with `px`. + +NOTE: The pixel is the only supported unit in image sizing right now. + +==== +.Image resizing specifying `height` and `width` attributes in pixels +[source] +---- +[height=150px,width=100px] +image::logo.jpg[] +---- +==== + +In the `height` and `width` attributes, the `px` suffix may be omitted. + + +==== +.Image resizing with values omitting `px` unit +[source,asciidoc] +-- +[height=150,width=100] +image::logo.jpg[] +-- +==== + +The `auto` value indicates that the dimension does not have a fixed size but +retain the aspect ratio of the original image. + +==== +.Aspect ratio is retained with `width` set to `auto` based on the value of `height` +[source,asciidoc] +-- +[height=150,width=auto] +image::logo.jpg[] +-- +==== + +An unspecified dimension is considered `auto`. + +==== +.Aspect ratio is retained when setting `height` but not `width` +[source,asciidoc] +-- +[height=150] +image::logo.jpg[] +-- +==== + +NOTE: Treatment of image resizing may slightly differ across output formats. + + +=== Captions and titles + +As elsewhere in Metanorma, the caption of an image (of the figure containing the image) +is set with a line prefixed with dot above the image. + +[source,asciidoc] +-- +.Caption +image::logo.jpg[] +-- + +[source,asciidoc] +-- +image::logo.jpg[title=Caption] +-- + +NOTE: Similar to Asciidoctor AsciiDoc, the `title` attribute is treated as +identical to the dot-prefixed caption. + + +Metanorma supports a `title` attribute on images for accessibility, which is +distinct from the figure caption. +This is entered in Metanorma as the `titleattr` attribute: + +[source,asciidoc] +-- +[titleattr=Title Attribute] +image::logo.jpg +-- + +Or + +[source,asciidoc] +-- +image::logo.jpg[titleattr=Title Attribute] +-- + +Both captions and titles could be used together. + +[source,asciidoc] +-- +.Rice husk separation in rice farm at Breton near Dinan +image::logo.jpg[titleattr=Photo of rice husks being separated] +-- + +NOTE: The `titleattr` attribute does not get rendered in Word output due to Word +limitations. Word only supports a single image "`Alt Text`", which would be set +by the caption. +Word's description of "`Alt Text`" is: +"`How would you describe this object and its context to someone who is blind?`". + + +==== Other attributes + +NOTE: For general attributes of the `image` command, please refer to the https://docs.asciidoctor.org/asciidoc/latest/macros/image-ref/[AsciiDoc image documentation]. The following paragraphs describe Metanorma-specific behavior. + diff --git a/author/topics/document-format/indexes.adoc b/author/topics/blocks/indexes.adoc similarity index 82% rename from author/topics/document-format/indexes.adoc rename to author/topics/blocks/indexes.adoc index 5e1a1ad9..dfd9ace3 100644 --- a/author/topics/document-format/indexes.adoc +++ b/author/topics/blocks/indexes.adoc @@ -140,6 +140,24 @@ ____ *** technique, _see also_ Jimi Hendrix ____ +Only one target is to be given per macro; if there are multiple targets, they need to be +specified in separate macros. Metanorma will concatenate them correctly. + +[source,adoc] +-- +index:also[guitar,electric,technique,Jimi Hendrix] +index:also[guitar,electric,technique,Eric Clapton] +-- + +Rendered as: + +____ +* guitar +** electric +*** technique, _see also_ Jimi Hendrix, Eric Clapton +____ + + === Index placement If any index terms are present in a document, and the current flavour supports @@ -184,6 +202,35 @@ levels deep. In some flavours, a separate table of contents is inserted for figures, tables, and recommendations. +=== Automated table of contents generation + +The table of contents is generated automatically for Word, HTML, and PDF output. + +* In Word, it takes the form of a normal Word Table of Contents; the page numbers +are not populated when the document is generated, and the table of contents needs +to be refreshed (Right Click: Update Field). +* In HTML, it takes the form of a side panel. In PDF, it takes the form of an +introductory table of contents; because the PDF is generated from HTML in Metanorma, +there are no page numbers in the table of contents. + +By default, the table of contents includes two levels of heading. More levels of +heading can be set by using the document attribute `:toclevels:`; e.g. +`:toclevels: 3` for three levels of heading included. The number of levels of heading +to include can be set separately for HTML and for DOC/PDF, by using the document +attributes `:htmltoclevels:`, `:pdftoclevels:` and `:doctoclevels:`. + +The location of the table of contents is set by default for each flavour, and is normally +at the start of the document preface. If the user wishes to insert a signpost for tables of content, +the clause type `toc` is reserved to indicate +where the table of contents will go. But Metanorma by default will not allow any flexibility +in where the table of contents will be rendered --- and will move it to the start of the preface. + +[source,adoc] +---- +[.preface,type=toc] +== Table of contents +---- + === Using the `toc` command to generate a ToC A manual table of contents command has been added to diff --git a/author/topics/blocks/lists.adoc b/author/topics/blocks/lists.adoc new file mode 100644 index 00000000..caf7212a --- /dev/null +++ b/author/topics/blocks/lists.adoc @@ -0,0 +1,241 @@ +--- +layout: author-docs +title: Lists +--- +== General + +tag::tutorial[] + +Metanorma AsciiDoc supports three types of lists: + +* Unordered lists +* Ordered lists +* Definition lists + +== Unordered lists + +Unordered lists are bulleted lists, entered using the asterisk (`*`) symbol. +Unordered lists can be nested by prefixing additional asterisks. + +[source,adoc] +---- +The main changes compared to the previous edition are: + +* updated normative references; +* deletions: +** deletion of 4.3. [nested list item] +** deletion of 4.4. [nested list item] +---- + + +== 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 defined style of the Metanorma flavor. + +[source, AsciiDoc] +---- +. First Step +. Second Step +. Third Step +---- + + +== Definition lists + +Definition lists pair a term and a description together in a list, separated by +two or more colon symbols (`:`). + +Definition lists are often used to define abbreviations, units or symbols. + +NOTE: In Metanorma, the Terms section uses a special syntax for defining terms. + +NOTE: Definition lists are also sometimes called https://docs.asciidoctor.org/asciidoc/latest/lists/description/[description lists]. + +Definition lists follow the syntax of: +---- +`term:: Definition` +---- + +// TODO: In Metanorma PDFs stem:[w] compiled to a lowercase omega. How to determine which alphabet to use? +.Example of definitions for units +[source,adoc] +---- +stem:[w]:: is the mass fraction of grains with a particular defect in the test sample; +stem:[m_D]:: is the mass, in grams, of grains with that defect; +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~_. + +end::tutorial[] + + +== Referencing a list item + +You can reference a single list item using the +link:/author/topics/inline_markup/links[internal reference] mechanism. + +Simply assign an anchor before the list item: + +.Example of list items that can be referenced +[source,adoc] +-- +. Ordered list +.. [[id1]] This is the first list item +... [[id2]] This is a list sub-item +-- + + +== List items with more than one paragraph + +Metanorma AsciiDoc supports multiple paragraphs within a single list item +through https://asciidoctor.org/docs/user-manual/#list-continuation[list continuation]. + +NOTE: In HTML output, all the paragraphs within a list item will be aligned. + +[NOTE] +==== +.Microsoft Word caveats + +- For list items containing multiple paragraphs, + Metanorma attempts to format them appropriately by using custom + list continuation styles (`ListContLevel1` etc.) applied to groups + of paragraphs; however, you should check the output document and + may need to manually intervene. + +- In Microsoft Word, each list entry must be a single paragraph. + Metanorma is employing a workaround through list continuation styles, + and results may be unexpected if the list is edited. +==== + + + +== List styling + +=== Unordered list styling + +The default styling for unordered lists are bullets. Metanorma does not support +other styles for unordered lists. + + +=== Ordered list styling + +==== General + +The default styling for ordered lists follow the specifications of ISO/IEC DIR 2 +and is the same for each output type: + +- level 1: _a), b), c)_ (`alphabetic`), +- level 2: _1), 2), 3)_ (`arabic`), +- level 3: _i), ii), iii)_ (`roman`), +- level 4: _A), B), C)_ (`alphabetic_upper`), +- level 5: _I), II), III)_ (`roman_upper`). + +NOTE: This labeling applies to all output formats, including PDF, HTML and Word. + + +==== Step lists + +In some situations an integer-numbered list is needed for specification +of process steps. + +In certain flavours (NIST, ITU, OGC), `class=steps` is used to override the +default numbering, and use Arabic numbering as the base instead: + +* level 1: _1), 2), 3)_ +* level 2: _a), b), c)_ +* level 3: _i), ii), iii)_ +* level 4: _A), B), C)_ +* level 5: _I), II), III)_ + + +==== Specification of start label + +The `start` attribute can be specified for ordered lists to specify the start +label of the ordered list. + +NOTE: The `start` attribute for ordered lists is only allowed by certain Metanorma +flavors, such as BIPM and ISO. This is because of the difficulty of realising +the list numbering starting other than at 1 in autonumbered lists in Word HTML. + + +==== Specification of list type + +The `type` attribute can be used to specify the list numbering using values from +above. Manually-styled lists are not supported by all flavors. + +The accepted values are: + +`alphabetic`:: _a), b), c)_ +`arabic`:: _1), 2), 3)_ +`roman`:: _i), ii), iii)_ +`alphabetic_upper`:: _A), B), C)_ +`roman_upper`:: _I), II), III)_ + +.Example for a manually-styled list +==== +[source,adoc] +---- +[type="alphabetic_upper"] +. First as "A" +. Second as "B" + +[type="roman_upper"] +. First as "I" +. Second as "II" +---- +==== + + +[NOTE] +-- +This is a historical note that applies to `isodoc` v1.3.0 to v2.0.2. + +The `type` attribute, with acceptable values listed in the list above, +could be used to allow specifying labels of an ordered +list [added in https://github.com/metanorma/isodoc/releases/tag/v1.3.0]. + +In Word rendering the `type` attribute is always ignored in favor of +ISO/IEC DIR 2 compliant labelling. + +As of v2.0.3, the ability to specify the `type` attribute has been +retracted [added in https://github.com/metanorma/isodoc/releases/tag/v2.0.3], +because of the bugs it introduces with list cross-referencing and rendering. +-- + + +=== Definition list styling + +Definition lists are rendered by default horizontally, with the definition in +the same line as the term. + +In Word output, definition lists are rendered as true tables. +Word defines the width of the term column using the auto-width algorithm, and +might cause words to break. + +To ensure that terms are rendered in a single line in Word, you need to use +non-breaking spaces and non-breaking hyphens in HTML escape notation. + +* Non-breaking spaces: `\ ` or `\ ` +* Non-breaking hyphens `\‑` + +.Example for a non-breaking sentence +==== +Instead of entering: + +[source,adoc] +---- +This is a non-breaking term. +---- + +Enter: + +[source,adoc] +---- +This\ is\ a\ non\‑breaking\ term. +---- +==== diff --git a/author/topics/blocks/math.adoc b/author/topics/blocks/math.adoc new file mode 100644 index 00000000..798255c2 --- /dev/null +++ b/author/topics/blocks/math.adoc @@ -0,0 +1,278 @@ +--- +layout: author-docs +title: Mathematical Expressions +--- +== Mathematical Expressions + +Metanorma AsciiDoc accepts mathematical input in these formats: + +* AsciiMath +* LaTeX math +* MathML + +Math can be entered using one of the following mechanisms: + +* the `\stem:[...]`, `\asciimath:[...]` and the `\latexmath:[...]` commands; and +* the `[stem]`, `[asciimath]`, `[latexmath]` blocks delimited with `\++++{blank}` + +The math syntax used by `\stem:[...]` and `[stem]` blocks depends on +the value of the document attribute `:stem:`. It can be set to: + +`:stem: latexmath`:: any markup within `stem` is interpreted as LaTeX math +`:stem: asciimath`:: any markup within `stem` is interpreted as AsciiMath +`:stem:`:: (default) when left empty, AsciiMath is selected + +`\stem:[...]` and `[stem]` markup that contains MathML markup +(as detected by an initial ``) is interpreted as MathML. + +MathML is used as the internal representation of STEM expressions in Metanorma. + + +=== Using AsciiMath + +AsciiMath can be entered using the `\asciimath:[...]` command and the +`[asciimath]` block delimited with `\++++{blank}`. +The `\stem:[]` and `[stem]` blocks can also be used if the document attribute +`:stem: asciimath` has been specified in the document. + +AsciiMath is converted into MathML using the +https://github.com/asciidoctor/asciimath[asciimath] gem. + +The syntax of AsciiMath recognised by the `asciimath` gem is more strict +than the common MathJax processor of AsciiMath. + +For example, `asciimath` insists on numerators being bracketed. + +[example] +.Usage of AsciiMath in IEV (IEV 103-01-03) +==== +[source,asciidoc] +---- +The derivative of a distribution stem:[D] is another distribution +stem:[D'] defined for any function stem:[f](stem:[x]) by +stem:[D^( ' ) ( f ) = - D ( d f // d x )]. +---- +==== + + +[example] +.Usage of AsciiMath in ISO 10303-55 (ISO 10303-55, Clause 2) +==== +[source,asciidoc] +---- +[stem] +++++ +f -= lambda x (a * x + b) +++++ +---- +==== + +WARNING: Some math expressions are NOT supported by AsciiMath. In that case it +is necessary to use LaTeX math or MathML input. + + +=== Using LaTeX math + +LaTeX math can be entered using the `\latexmath:[...]` command and the +`[latexmath]` block delimited with `\++++{blank}`. +The `\stem:[]` and `[stem]` blocks can also be used if the document attribute +`:stem: latexmath` has been specified in the document. + +LaTeX math is converted into MathML using the +https://github.com/plurimath/latexmath[latexmath] gem, which generates +output compliant with the deterministic output of the +https://dlmf.nist.gov/LaTeXML/[NIST LaTeXML] suite. + +NOTE: LaTeX math parsing of the +https://dlmf.nist.gov/LaTeXML/manual/commands/latexmlmath.html[LaTeXML's `latexmlmath` command] +is deterministically accurate. +The https://github.com/plurimath/latexmath[latexmath] gem was created +to generate identical output to the `latexmlmath` command. + +Unicode characters in the LaTeX source are translated into LaTeX escapes +through the https://github.com/metanorma/unicode2latex[unicode2latex] gem. + +[example] +.Example of using LaTeX Math in ISO 10303-110 (ISO 10303-110, Clause 4) +==== +[source,asciidoc] +---- +The only change from the above example would be the +nondimensionalization of viscosity, which would become, +latexmath:[\tilde{\tilde{\mu}} = mu / (rho_infty c_infty L)]. +---- +==== + +[example] +.Another example of using LaTeX Math in ISO 10303-110 (ISO 10303-110, Clause 4) +==== +[source,asciidoc] +---- +[latexmath] +++++ +\begin{array}{c@{\qquad}c@{\qquad}c} + \tilde{x} = x/L, \tilde{u} = u/c_\infty, \tilde{\rho} = \rho/\rho_\infty, + \tilde{y} = y/L, \tilde{v} = v/c_\infty, \tilde{p} = p/(\rho_\infty c_\infty^2), + \tilde{z} = z/L, \tilde{w} = w/c_\infty, \tilde{\mu} = \mu/\mu_\infty, +\end{array} +++++ +---- +==== + + +The LaTeX math `eqnarray` environment is not supported in Metanorma as +it is not supported by LaTeXML and the latexmath gem. +It is also not recommended by the general +LaTeX community due to inconsistencies in vertical alignment and other aspects +(see link:https://www.tug.org/pracjourn/2006-4/madsen/madsen.pdf[Madsen]). + +The proper LaTeX math syntax used to replace existing `eqnarray` +equations is to place the equations in separate blocks concatenated +with `+`. + +[example] +.Replacing LaTeX math `eqnarray` in Metanorma with separate equations +==== +These equations using the `eqnarray` environment: + +[source,asciidoc] +-- +[latexmath] +++++ +\begin{eqnarray*} + \bf{z^\prime} & = & \bf{\zeta} \\ + \bf{x^\prime} & = & \langle \bf{\eta} \times \bf{\zeta} \rangle +\end{eqnarray*} +++++ +-- + +should be re-arranged as: + +[source,asciidoc] +-- +[latexmath] +++++ +\bf{z^\prime} = \bf{\zeta} +++++ ++ +[latexmath] +++++ +\bf{x^\prime} = \langle \bf{\eta} \times \bf{\zeta} \rangle +++++ +-- +==== + +== Formulae + +=== General + +Formulae are marked up as `[stem]` blocks. + +=== Equations + +In most flavours, equations and inequalities are both referenced in the same +way, as "`Formula`". + +In some flavours (e.g. ITU), they are referenced differently as "`Equations`" +and "`Inequalities`". + + +=== Inequalities + +Inequalities are indicated through the option attribute `%inequality`: + +[source,asciidoc] +-- +[stem%inequality] +++++ +{formula-content} +++++ +-- + +Where: + +* `{formula-content}` is content within a formula. + +[example] +.Example of encoding an inequality formula +==== +[source,asciidoc] +-- +[stem%inequality] +++++ +A < B +++++ +-- + +renders as: + +image::/assets/author/topics/document-format/text/fig-stem-inequality.png[Example of a block stem inequality in Metanorma] +==== + +=== Key + +Explanation of symbols used in the formula is specified in a "key" list, which is +specified as a definition list with the `[%key]` +option [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.3]. + +The syntax is as follows: + +[source,asciidoc] +-- +[stem] +s++++ +{some-formula} +++++ + +[%key] +stem:[{some-symbol}]:: {symbol-description} +-- + +Where: + +* `{some-formula}` represents content within a formula +* `{some-symbol}` represents a symbol within the formula +* `{symbol-description}` is text that describes information about the symbol + +[example] +.Example of including a key for a formula (`stem`) block +==== +[source,asciidoc] +-- +[stem] +++++ +w = (m_D) / (m_s) +++++ + +[%key] +stem:[w]:: is the mass fraction of grains with a particular defect in the test sample; +stem:[m_D]:: is the mass, in grams, of grains with that defect; +stem:[m_S]:: is the mass, in grams, of the test sample. +-- + +renders as: + +image::/assets/author/topics/document-format/text/fig-stem-equality.png[Example of a block stem equation in Metanorma] +==== + +Instead of `[%key]`, the definition list can also be preceded with a paragraph +containing the English word `where`, though this is not recommended practice. + +[example] +.Example of including a key for a formula (`stem`) block using the `where` keyword +==== +[source,asciidoc] +---- +[stem] +++++ +w = (m_D) / (m_s) +++++ + +where + +stem:[w]:: is the mass fraction of grains with a particular defect in the test sample; +stem:[m_D]:: is the mass, in grams, of grains with that defect; +stem:[m_S]:: is the mass, in grams, of the test sample. +---- +==== + diff --git a/author/topics/blocks/passthroughs.adoc b/author/topics/blocks/passthroughs.adoc new file mode 100644 index 00000000..b0d02d23 --- /dev/null +++ b/author/topics/blocks/passthroughs.adoc @@ -0,0 +1,126 @@ +--- +layout: author-docs +title: Passthrough to output formats +--- +== Passthrough to output formats + +=== Passthrough blocks + +Passthrough text, such as XML tags, intended to be rendered in a target format +unaltered, can be entered as a passthrough +block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.27]. + +This functionality enables automated processing, custom tagging, hacking into +intermediary formats and experimental development of Metanorma output. + +WARNING: A broken Metanorma XML file will cause rendering of target formats to +also break. Use with caution. + +Passthrough intended to be rendered in Metanorma XML (such as Metanorma XML tags), +generated from Metanorma AsciiDoc input, can be entered as a +passthrough block [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1], +with no format indication. + +[example] +.Using passthrough XML tags in the Metanorma XML target +==== +[source,asciidoc] +-- +++++ + +++++ +-- +==== + +WARNING: Passthrough text may break the structure of the output +format -- it is the user's responsibility to ensure the integrity +of the resulting structure (e.g. XML) is retained. + +Passthrough intended to be rendered in a target format must be specified with +a format indication corresponding to one or more of the existing output formats +of Metanorma in a comma-delimited manner +(not limited to: `html`, `doc`, `pdf`, `rfc`, `sts`). + +[example] +.Using passthrough XML tags in the RFC XML target +==== +[source,asciidoc] +-- +[format=rfc] +++++ + + +++++ +-- +==== + +=== Passthrough inline text + +Metanorma AsciiDoc supports the following syntaxes for inline passthrough. + +Passthrough of text that does not involve XML structural syntax can be realized +in any of the following syntaxes: + +[source,adoc] +---- +// syntax 1 ++this is passed through+ + +// syntax 2 ++++this is passed through too+++ + +// syntax 3 +pass:[also passed-through] +---- + +[example] +.Example of specifying passthrough text +==== +[source,asciidoc] +-- +This is a special pass:[𝒞𝓪𝓼𝓮]. +-- +==== + +For passthrough of XML syntax or tags to Metanorma XML, which will require +special character processing, use the following command: + +[source,adoc] +---- +pass:c[xml-content] +---- + +Where: + +* `xml-content` is content that contains XML or SGML tags + +[example] +.Example of specifying passthrough XML content +==== +[source,asciidoc] +-- +pass:c[ᏚᎢᎵᎬᎢᎬᏒ] +-- +==== + +If the passthrough text is intended for one or more target formats, the formats +needs to be specified with the `pass-format` +command [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.7]. + +[source,adoc] +---- +pass-format:FORMAT[...] +---- + +Where: + +* `FORMAT` is a comma-delimited list of target formats. + +[example] +.Example of specifying passthrough for selected target formats +==== +[source,asciidoc] +-- +pass-format:rfc[ᏚᎢᎵᎬᎢᎬᏒ] +-- +==== diff --git a/author/topics/blocks/pseudocode.adoc b/author/topics/blocks/pseudocode.adoc new file mode 100644 index 00000000..8b549e55 --- /dev/null +++ b/author/topics/blocks/pseudocode.adoc @@ -0,0 +1,86 @@ +--- +layout: author-docs +title: Pseudocode +--- +== Pseudocode + +Pseudocode is a mix between formal math with code like properties commonly +used in computer science and related fields. + +Unlike source code, pseudocode is typically in a proportional font, but it +still needs to be indented to reflect code structure. +Moreover, pseudocode typically requires source code highlighting +such as boldface; but unlike well-defined computer languages, there is no +guaranteed way of automating such highlighting. + +Pseudocode is supported in Metanorma using the `pseudocode` block with these +properties: + +* text within a pseudocode block is treated as normal text, including + respect for inline formatting; + +* lines do not need to be separated by line breaks, although two carriage + returns in a row are still interpreted as a new + paragraph. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10] + +* indentation spaces at the start of each line are preserved, by converting + them into non-breaking spaces; initial tabs are converted into four + non-breaking spaces. + +The syntax is as follows: + +[source,asciidoc] +-- +[pseudocode] +==== +normal text + stem:[math] + _italics_ [smallcap]#small caps text# +*bolded text* +==== +-- + +[example] +.Example of using the pseudocode block with flow operators +====== +[source,asciidoc] +-- +[pseudocode] +==== +*do in-parallel* + [smallcap]#SharedAccess# +*enddo* + +[smallcap]#ExclusiveAccess# stem:[-=] + *if* _ag.mode_ = _exclusive_ stem:[^^ AA t in] [smallcap]#Token# : _t.available_ *then* + *do forall* _t_ : stem:[in] [smallcap]#_Token_# + _t.owner_ := _ag_ + *enddo* + *endif* +==== +-- +====== + +[example] +.Example of using the pseudocode block with numeric values (from ISO 8000-118) +====== +[source,asciidoc] +-- +[pseudocode] +==== +EncodeGroundLevel(_groundLevel_) + + *if not* stem:[-19652 <= "_groundLevel_" <= 19651] + *raise* _out of bounds error_ + *endif* + + _groundLevel_ = _groundLevel_ + 19652 + + *return* [smallcap]#EncodeBase34#(_groundLevel_) +==== +-- + +renders as (PDF): + +image::/assets/author/topics/document-format/text/fig-pseudocode-8000-118.png[Pseudocode usage in ISO 8000-118] +====== diff --git a/author/topics/blocks/quotes.adoc b/author/topics/blocks/quotes.adoc new file mode 100644 index 00000000..efc68d91 --- /dev/null +++ b/author/topics/blocks/quotes.adoc @@ -0,0 +1,46 @@ +--- +layout: author-docs +title: Quotes +--- +== Block quotes + +Block quotes are preceded with an author and a citation. + +* The citation is expected to be in the same format as all other citations, +which is a cross-reference optionally followed by text. + +* The citation may include the bibliographic sections referenced. + +[source,asciidoc] +-- +[quote,{attribution},{citation}] +____ +{content} +____ +-- + +Where: + +* `{attribution}` is the rendered name of the source +* `{citation}` is a valid citation reference (citation anchor, optionally followed by locality) +* `{content}` is the quotation content + +[example] +.Example of a block quote, quoting a section from an ISO deliverable +==== +[source,asciidoc] +-- +[quote, ISO, "ISO7301,section=1"] +_____ +This International Standard gives the minimum specifications for rice +(_Oryza sativa_ L.) which is subject to international trade. It is applicable to +the following types: husked rice and milled rice, parboiled or not, intended for +direct human consumption. It is neither applicable to other products derived +from rice, nor to waxy rice (glutinous rice). +_____ +-- + +renders as + +image::/assets/author/topics/document-format/text/fig-block-quote.png[Illustration of a block quote in Metanorma] +==== diff --git a/author/topics/document-format/requirements-modspec.adoc b/author/topics/blocks/requirements-modspec.adoc similarity index 95% rename from author/topics/document-format/requirements-modspec.adoc rename to author/topics/blocks/requirements-modspec.adoc index a402ce13..524a4102 100644 --- a/author/topics/document-format/requirements-modspec.adoc +++ b/author/topics/blocks/requirements-modspec.adoc @@ -831,6 +831,8 @@ identifier:: http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs target:: http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-building indirect-dependency:: http://www.opengis.net/doc/IS/ogcapi-features-1/1.0#ats_core classification:: Target Type:Web API +conformance-test:: /conf/core/conformance-success +conformance-test:: /conf/core/tc-op ==== ---- @@ -842,10 +844,12 @@ ____ |=== 2+a|Conformance Class 1 -2+a|http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs -|Requirements Class |_Requirements Class 'Coordinate Reference Systems by Reference'_ -|Dependency |http://www.opengis.net/doc/IS/ogcapi-features-1/1.0#ats_core +|Identifier |`http://www.opengis.net/spec/ogcapi-features-2/1.0/conf/crs` +|Requirements Class |Requirements Class 1: `http://www.opengis.net/spec/CityGML-1/3.0/req/req-class-building` +|Dependency |`http://www.opengis.net/doc/IS/ogcapi-features-1/1.0#ats_core` |Target Type |Web API +|Conformance tests a|Abstract test A.1: `/conf/core/conformance-success` + +Abstract test A.2: `/conf/core/tc-op` |=== ____ ====== @@ -1112,7 +1116,6 @@ cross-reference, like `http://www.example.com/req/crs/crs-uri` instead of _Requirement Class 6_. ==== - ==== Referencing using predefined anchors This can be extended to cross-references. If the anchor of the requirement is @@ -1128,10 +1131,11 @@ known, a normal cross-reference can be marked up, as shown below. Renders (assuming that this is the 10th Requirement): -_Requirement 10_ +____ +Requirement 10: `http://www.example.com/req/crs/crs-uri` +____ ==== - ==== Referencing using instance identifiers However, not all ModSpec instances are assigned predefined anchors, especially @@ -1158,7 +1162,7 @@ identifier:: http://www.example.com/req/crs/crs-uri ==== ---- -It is possible to reference a ModSpec instance using its identifier instead of +--- it is possible to reference a ModSpec instance using its identifier instead of the anchor, as follows. .Cross-reference to a ModSpec instance using its identifier, displaying the instance's name @@ -1171,7 +1175,9 @@ xref:http://www.example.com/req/crs/crs-uri[] Renders (assuming that this is the 10th Requirement): -_Requirement 10_ +____ +Requirement 10: `http://www.example.com/req/crs/crs-uri` +____ ==== Metanorma treats them as fully equivalent, and will render them in the same way, @@ -1180,7 +1186,38 @@ as a numbered label (_Requirement Class 6_). NOTE: As a limitation of syntax, URIs cannot be processed correctly within `<<..>>`. The `xref:...[]` command needs to be used instead. -To make the cross-reference render the identifier value of the instance itself, +==== Cross-reference rendering + +Following Modspec practice, all cross-references to Modspec instances from within another +Modspec instance are rendered +along with the URI identifier of that instance where available; the URI is truncated +with reference to an identifier base (see <>). + +So a reference to `<>` or to `xref:http://www.example.com/req/crs/crs-uri[]` made within +a Modspec instance will render as + +____ +Requirement 10: `http://www.example.com/req/crs/crs-uri` +____ + +If the reference occurs outside a Modspec instance however, e.g. in a normal clause, +it will be made like any other cross-reference to a requirement, without the URI. + +____ +Clause 7.3.2, Requirement 10 +____ + +If you want the reference made outside a Modspec instance to render as if it is inside a Modspec +instance, with the URI, use `style=modspec%`: + +[source,adoc] +---- +xref:http://www.example.com/req/crs/crs-uri[style=modspec%] + +<> +---- + +To make the cross-reference render the URI identifier value of the instance itself, while still hyperlinking to the correct identifier, you can specify `style=id%` as the cross-reference text, as follows. @@ -1200,6 +1237,32 @@ Renders as: This will also highlight the URI text as subject to truncation, with reference to identifier bases. +In some flavours (ISO as of this writing), the automatically generated cross-references +within requirements (listings of provisions, tests, child and parent requirements) is different +from the default rendering of cross-references in documents. In order to use the same +cross-reference style as occurs inside of requirements, you can specify +`style=modspec%` [added in https://github.com/metanorma/mn-requirements/releases/tag/v0.3.1]. + +For example, in ISO, in the main body of text + +==== +[source,adoc] +---- +xref:http://www.example.com/req/crs/crs-uri[style=modspec%] + +xref:http://www.example.com/req/crs/crs-uri[] +---- + +Renders as: + +____ +Requirement 2: Widgets + +Table 9, Requirement 2 +____ + +==== + [[identifier-base]] ==== Identifier base pattern @@ -1295,9 +1358,9 @@ and to the identifier labels of requirements. [example] .Setting a document-wide identifier base prefix -==== +===== [source,adoc] ------ +---- :modspec-identifier-base: http://www.example.com Refer to @@ -1318,8 +1381,7 @@ description:: Some description. identifier:: http://www.example.com/req/class1/req1 statement:: A requirement. ==== - ------ +---- Renders as: @@ -1344,11 +1406,11 @@ h| Included in | Requirement class 1: `/req/class1` h| Statement | A requirement. |=== ____ -==== +===== [example] .Setting a identifier base prefix at a class instance -==== +===== [source,adoc] ----- [requirement,type=requirements_class] @@ -1366,7 +1428,6 @@ description:: Some description. identifier:: http://www.example.com/req/class1/req1 statement:: A requirement. ==== - ----- Renders as: @@ -1388,11 +1449,11 @@ h| Included in | Requirements class 1: `/class1` h| Statement | A requirement. |=== ____ -==== +===== [example] .Setting identifier base prefixes for document-wide and at the class instance level -==== +===== [source,adoc] ----- :modspec-identifier-base: http://www.example.com @@ -1456,7 +1517,7 @@ h| Included in | Requirements class 2: `/req/class2` h| Statement | See also Requirement 1: `/req/class1/req1` |=== ____ -==== +===== === Rendering of ModSpec instances diff --git a/author/topics/document-format/requirements-mrr.adoc b/author/topics/blocks/requirements-mrr.adoc similarity index 100% rename from author/topics/document-format/requirements-mrr.adoc rename to author/topics/blocks/requirements-mrr.adoc diff --git a/author/topics/document-format/requirements.adoc b/author/topics/blocks/requirements.adoc similarity index 100% rename from author/topics/document-format/requirements.adoc rename to author/topics/blocks/requirements.adoc diff --git a/author/topics/blocks/source.adoc b/author/topics/blocks/source.adoc new file mode 100644 index 00000000..9a45f4d8 --- /dev/null +++ b/author/topics/blocks/source.adoc @@ -0,0 +1,148 @@ +--- +layout: author-docs +title: Source code +--- +== Source code + +=== Basics + +tag::tutorial[] + +Metanorma AsciiDoc supports code blocks via the `[source]` block. + +The source code block takes a pre-formatted text block rendered in monospace +font, with line breaks and space indentations preserved. + +The syntax is as follows: + +[source,asciidoc] +-- +[source] +---- +Rendered in monospace text +---- +-- + +[example] +.Example of rendering source code without language specification +==== +[source,asciidoc] +-- +[source] +---- +Identifier(latitude, longitude, elevation, elevationType) + + return concat( + "ISO.NLI", + EncodePoint(latitude, longitude), + EncodeElevation(elevation, elevationType) + ) +---- +-- +==== + + +It is possible to specify the computer language used in the `[source]` block +to enable source code highlighting (syntax highlighting) for supported +languages. + +Metanorma integrates the http://coderay.rubychan.de[CodeRay syntax highlighter] +which supports the following list of languages represented by codes: + +* `c` +* `clojure` +* `css` +* `delphi` +* `diff` +* `erb` +* `go` +* `groovy` +* `haml` +* `html` +* `java` +* `java_script` +* `json` +* `lua` +* `php` +* `python` +* `raydebug` +* `ruby` +* `sass` +* `sql` +* `taskpaper` +* `xml` +* `yaml` + +NOTE: The full list of supported file extensions is provided by https://github.com/rubychan/coderay/blob/c25e8ef53cef6e72b98547139a6a27bdd4f1aaf3/lib/coderay/helpers/file_type.rb#L79-L131[CodeRay]). + + +[source,asciidoc] +-- +[source,language] +---- +Rendered in monospace with syntax highlighting +---- +-- + +[example] +.Example of rendering source code with language specification and syntax highlighting +==== +[source,asciidoc] +-- +.Ruby code for MyIdentifier#format <1> +[source,ruby] <2> +---- <3> +class MyIdentifier <4> + def format(string) + "did:#{string}" + end +end +---- <5> +-- +<1> (Optional) Title for source block +<2> (Optional) `ruby` here denotes the language used within the source block. +<3> Starting source delimiter of 4 `-` signs +<4> Source content +<5> Ending source delimiter of 4 `-` signs + +==== + +end::tutorial[] + + +=== Markup in source code blocks + +It is sometimes necessary to introduce markup into source code. For example, +hyperlinking words in source code to external definitions, or else introducing +formatting in lieu of automated highlighting. + +In order to achieve this, Metanorma allows inline AsciiDoc markup to be +introduced into source code, isolating it from the rest of the source code +through +delimiters. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.4] + +By default, the delimiters are `{{{` and `}}}`. These can be overridden (in case +`{{{` and `}}}` are already used in the document) through the document attributes +`:sourcecode-markup-start:` and `sourcecode-markup-end:`. + +[example] +.Example of applying inline formatting to source code blocks +==== +[source,asciidoc] +---- +[source,ruby] +-- +{{{*def*}}} method1(x) + {{{<>}}}(x) + 3 +end +-- +---- + +renders as: + +-- +*def* method1(x) + +    link:/[method2](x) + 3 + +end +-- +==== diff --git a/author/topics/blocks/tables.adoc b/author/topics/blocks/tables.adoc new file mode 100644 index 00000000..741d2da5 --- /dev/null +++ b/author/topics/blocks/tables.adoc @@ -0,0 +1,216 @@ +--- +layout: author-docs +title: Tables +--- +== General + +Tables are useful for displaying data of the same structure. + +Metanorma AsciiDoc tables are required to handle the full range of complexity +of standardization documents, and is therefore significantly more +powerful than typical AsciiDoc tables. + +NOTE: Typical AsciiDoc already handles tables very well for a non-XML markup language. + + +== Basics + +tag::tutorial[] +Metanorma AsciiDoc supports all basic table syntaxes of AsciiDoc, including: + +* cells spanning multiple rows and columns; +* horizontal alignment; +* vertical alignment [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3]. + +Given AsciiDoc is a plain-text format, it uses specific symbols to determine +where new table rows and columns begin. + +.Example of a simple AsciiDoc table +[source,adoc] +---- +[cols="1,1"] <1> +.A table with a title <2> +|=== <3> +|Cell in column 1, header row |Cell in column 2, header row <4> + +|Cell in column 1, row 2 +|Cell in column 2, row 2 <5> +|=== <6> +---- +<1> Optional table attributes that specifies the table structure. +The numbers specify the relative amount of spacing between the columns. +`cols="x,x"` indicates that there are two columns. +<2> The table title can be assigned by beginning a line with a dot `.`. Make +sure that there is no space between the dot and the first word of the heading. +<3> Starting table delimiter `|===` +<4> Header row. The line immediately after the starting delimiter is the header row. +To add a column, add a vertical bar `|` before the text that should be in the column. +<5> When using 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 table delimiter `|===` + +end::tutorial[] + +TIP: For table formatting options, such as joining cells or +setting text alignment, please refer to +https://docs.asciidoctor.org/asciidoc/latest/tables/align-by-cell/[AsciiDoc table documentation]. + + +== Column widths + +Table columns can have their widths set [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.3]. +Table column widths must be enumerated explicitly per column to generate column widths. + +* `[cols="a,a"]` would define two columns of equal widths. + +* `[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. + +[example] +.Example of table with equal width columns +==== +The following syntax will be processed as generating equal width columns. + +[source,adoc] +---- +[cols="1,1,1"] +---- +==== + +NOTE: In typical AsciiDoc, `[cols="3"]` is considered a shorthand to +`[cols="1,1,1"]`, but this is not supported in Metanorma AsciiDoc. + + +== Table widths + +The table width can be set with the `width` +attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.21]. + +It could be either: + +* a percentage (e.g. `70%`); or +* a pixel count (e.g. `500px`). + +NOTE: The `width` attribute value aligns with HTML CSS and HTML 4 behavior. + +[source,asciidoc] +---- +[width=70%] +|=== +| Vehicle | Passenger + +| Mazda 3 | Bob +| Tesla Model Y | Alice + +|=== +---- + +Will result in the table width spanning 70% of the rendered output medium. + +NOTE: This feature is not supported in typical AsciiDoc. + +== Notes and footnotes + +Metanorma AsciiDoc tables behave differently from typical AsciiDoc +with notes and footnotes due to the requirements of standardization documents. + +Specifically: + +* table cell footnotes (`footnote:[...]`) are rendered inside the table; +* notes (`NOTE: ...`) following the table are rendered inside the table footer. + +NOTE: Typical AsciiDoc renders table cell footnotes inside the cell, +and notes trailing the table outside the table. + + +== Multiple header rows + +Metanorma AsciiDoc supports the option of multiple header rows via attribute +`headerrows` to deal with the complexity of standardization documents' tables +requiring labels, variables, and units to lining up in the header. + +[source,adoc] +---- +[headerrows=2] +|=== +.2+|Sample 3+^| Value +| Test A | Test B | Test C + +| Component 1 | Pass | Fail | Pass + +|=== +---- + +This renders as: + +|=== +.2+h|Sample 3+^h| Value +h| Test A h| Test B h| Test C + +| Component 1 | Pass | Fail | Pass + +|=== + +NOTE: This feature is not supported in typical AsciiDoc. + + +== Accessibility metadata + +Metanorma AsciiDoc supports assigning accessibility metadata for tables, +including alt text and summary text, via table attributes. + +`alt`:: alternate text that describes the table; +`summary`:: summary text that describes a summary of the content provided by the table. + +Both are rendered as a summary of the table for accessibility. + +NOTE: Alternate text is shown when the table can not be displayed (HTML only). + +.Example of assigning alt text and summary text +==== +[source,asciidoc] +---- +[alt=Table of tested components,summary=Table of components being tested in Tests A to C] +.2+|Sample 3+^| Value +| Test A | Test B | Test C + +| Component 1 | Pass | Fail | Pass + +|=== +---- +==== + +NOTE: This feature is not supported in typical AsciiDoc. + + + +== Complex table examples + +[[table-example-1]] +=== Example table 1 + +.Example of a more complex table +[source,adoc] +---- +[headerrows=2,alt=Table of maximum mass fraction of defects in husked rice,summary=Table enumerating the permissible mass fraction of defects in husked and various classes of milled rice,width=70%] +|=== +.2+|Defect 4+^| Maximum permissible mass fraction of defects in husked rice + +stem:[w_max] +| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice + +| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] | 1,0 | 0,5 | 1,0 | 0,5 + +|=== +---- + +which renders: + +.Illustration of a table in Metanorma (DOC output). Configuration: 70% of width, two header rows, one normal row, one footnote. +image::/assets/author/topics/document-format/text/fig-table.png[Illustration of a table in Metanorma (DOC output). Configuration: 70% of width, two header rows, one normal row, one footnote] + +=== Example table 2 + +https://raw.githubusercontent.com/metanorma/mn-samples-iso/main/sources/international-standard/body/body-en.adoc[Table 1 in the Metanorma ISO Rice example document] illustrates +a large range of table formatting options. Search for `#table1`. + diff --git a/author/topics/document-format/collections.adoc b/author/topics/collections.adoc similarity index 76% rename from author/topics/document-format/collections.adoc rename to author/topics/collections.adoc index c13cb83a..576f9fce 100644 --- a/author/topics/document-format/collections.adoc +++ b/author/topics/collections.adoc @@ -20,13 +20,6 @@ Metanorma XML): * PDF: treated as a single document, composed of the individual Metanorma documents. -NOTE: Collections are a work in progress as of this writing, and their -functionality is in flux as they are starting to be applied to flavours. - -NOTE: Currently collections are used in the BIPM flavour, and are in the process -of being applied to ISO standards. - - == Compiling collections Collections are compiled using the `metanorma` executable, as follows: @@ -71,10 +64,8 @@ Specifically, it: * uses the HTML index page template `collection_cover.html`. -Currently the `metanorma collection` executable presupposes that the individual +The `metanorma collection` executable presupposes that the individual metanorma collections are already compiled into XML. -// I don't know how to make that not happen, and would ask that Abu Nashir addresses that. - The compilation of the collection resolves any cross-references between files in the collection in preprocessing, so that they become simple hyperlinks. @@ -101,6 +92,12 @@ https://github.com/metanorma/metanorma/releases/tag/v1.3.5]. This is automatically included when `sectionsplit` is set in the Metanorma file, to break a single document up into multiple HTML files. +** `coverpage` gives the location of the HTML coverpage, as an alternative to the +`-c` argument above [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.7]. + +** `coverpage-style` gives the style of the PDF and HTML coverpage, if multiple styles are +offered [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.7]. + ** `bare-after-first` compiles the first HTML document in the collection complete (with coverpage and boilerplate), and all subsequent files with the `bare` option (i.e. without coverpage and @@ -125,7 +122,7 @@ in nested hierarchy (`manifest`) ** `docref` lists the documents to be used at that level of the manifest: it is a list of file paths relative to the manifest file (`fileref`) and document -identifiers (`identifier`). +identifiers (`identifier`). The documents are expected to be Metanorma Semantic XML documents. ** If `attachment` is `true`, the file is not a Metanorma document but an attachment, and is passed-through (i.e. not processed) [added in @@ -147,6 +144,8 @@ The following is an example collection manifest: ---- directives: - documents-inline + - coverpage: index.html + - coverpage-style: JACK bibdata: title: type: title-main @@ -199,6 +198,88 @@ final-content: Hic explicit ---- +=== Site manifest + +As noted, the collection manifest is expected to reference Semantic XML documents. +The starting point for generating a collection is Metanorma Asciidoctor +documents; in order to specify a collection and generate it as straightforwardly +as possible, the collection manifest should be accompanied by a +link:/_pages/install/usage#metanorma-site[site manifest], named `metanorma.ym1`, +specifying both the +component Asciidoctor files, and the collection manifest, as dependency files. +Site compilation will compile both the component files, and the collection +depending on them. This is done by running `metanorma site generate` in the same +directory as `metanorma.ym1`. + +Since Metanorma site compilation compiles documents to a `_site/documents` directory, +the collection manifest needs to reference the Semantic XML documents in that +same `_site/documents` directory. + +The following two files are examples of a site manifest and a collection manifest +compiled through `metanorma site generate`. + +`metanorma.yml`: + +[source,yaml] +---- +--- +metanorma: + source: + files: + - document.1.adoc + - document.2.adoc + - collection.yml + + collection: + organization: "British Standards Institute" + name: "Retrofitting dwellings for improved energy efficiency — Specification and guidance" +---- + +In the site manifest, the files to be compiled are listed under `metanorma.source.files`; +any YAML file in the list is assumed to be a collection manifest. + +The collection is specified in the site manifest with two attributes: a name for the +collection document, and an organization treated as the corporate author of the collection. +Both will feature in the index file of the documents generated in the site (`_site/index.html`), +and correspond to `bibdata.title.content` and `bibdata.copyright.owner.name` in the collection manifest. + +`collection.yml`: + +[source,yaml] +---- +--- +directives: + - documents-inline +bibdata: + type: collection + docid: + type: bsi + id: bsidocs +format: + - xml + - html + - presentation + - pdf +manifest: + docref: + - fileref: _site/documents/document.1.xml + identifier: bsidocs-1 + - fileref: _site/documents/document.2.xml + identifier: bsidocs-2 +prefatory-content: +| + +final-content: +| +---- + +Note that document.1.adoc and document.2.adoc are compiled to `_site` as part +of site compilation. The fileref attributes in the collection manifest need to point +to the Semantic XML where the site compilation deposits them, under `_site/documents`. +The collection generation also generates the collection in the same location, so there +is no need to specify a collection destination directory, `--output-folder` under `metanorma collection`. + + === Index page template The HTML index page template is currently realised as a Liquid template, which @@ -207,13 +288,23 @@ forms a sidebar for the display of the HTML content of each file. The following fields are defined: * `doctitle`, `docnumber`, etc.: Information derived from the Relaton YAML -description in the manifest. The field names are as defined for Liquid templates +description in the manifest of the entire collection. +The field names are as defined for Liquid templates in Metanorma: see link:/builder/topics/metadata-and-boilerplate[Metadata and Boilerplate]. * `navigation`: A nested list giving hyperlinks to the constituent documents, following the specification in the `manifest` field of the collection manifest. +* `nav_object`: The same nested list, presented as a recursive object, in order to allow +users to select only a subset of the navigation list for presentation [added in https://github.com/metanorma/metanorma/releases/tag/v1.6.4]. +It contains the following fields: +** title: the list title +** docrefs: a hyperlinked list of the documents at that level of the manifest +** children: an array of child manifests +* `prefatory-content`: Prefatory content from the collection manifest [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.6]. +* `final-content`: Final content from the collection manifest [added in https://github.com/metanorma/metanorma/releases/tag/v1.5.6]. + [[collection-cross-references]] == Cross-references @@ -528,6 +619,8 @@ This is an introduction added to the Received document embed::received.adoc[] +The embedded document can be + == Colophon ---- @@ -591,3 +684,51 @@ This is content == Colophon ---- + +NOTE: As with Asciidoctor `include::[]`, Asciidoctor is unable to locate assets such as images if the +embedded document is in a different directory from the containing document: Asciidoctor lacks a mechanism +of specifying asset location relative to the current document, as opposed to the initial document. +For that reason, if you embed documents that reference files, you will need to put both documents in the +same folder, in a flat hierarchy. + +Documents can be embedded at multiple levels; the current implementation presupposes +that any document can only embed a single document, and that the embedding documents +only involve substituted clauses, or prefatory clauses (e.g. the original foreword, +supplemented by a regional foreword, and/or a national foreword). + +It is possible to cite the embedded document from the embedding document, through +a cross-reference to an anchor on the `embed::` directive: if no display text is supplied, +the cross-reference is populated with the document identifier of the +embedded document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.10]: + +For example, if + +[source,asciidoc] +---- += Document 1 +:docidentifier: SHQ XYZ 123A + +== Introduction + +This is an introduction added to the Received document <> + +[[id]] +embed::received.adoc[] +---- + +embeds the document + +[source,asciidoc] +---- += Document 1 +:docidentifier: XYZ 123 + +== Foreword + +This is the foreword +---- + +Then `<>` will be rendered as __XYZ 123__, the embedded document identifier; +and the `<>` cross-reference will hyperlink to the first header within the +embedded document (the Foreword, in this case). + diff --git a/author/topics/creating_new_document.adoc b/author/topics/creating_new_document.adoc new file mode 100644 index 00000000..ee59fb4a --- /dev/null +++ b/author/topics/creating_new_document.adoc @@ -0,0 +1,90 @@ +--- +layout: author-docs +title: Creating a new Metanorma document +--- +//If changes in this document are made, double check if author/concepts/metanorma_workflow.adoc is still up-to date. + +include::../../author/concepts/metanorma_workflow.adoc[tags=creation] + +== How to create an empty Metanorma document + +Follow these steps to create a new Metanorma document: + +. Open a text editor, for example, https://atom.io/[Atom] or https://code.visualstudio.com/[Visual Studio Code]. +. Create a new AsciiDoc document by creating a new file with the extension `.adoc` (AsciiDoc). ++ +The file should look like this: `filename.adoc` +. Write the document header that contains metadata about your project. A header contains attributes and values, such as: `doctype: standard`. Please refer to the link:/author/topics/metadata/[Adding metadata] section to learn more about the document header. +. Write down your content using Metanorma AsciiDoc markup. +. Save the file to the desired location. + + +== How to use a template +NOTE: Not all organizations have templates, and not all document types are supported. Head to the https://github.com/orgs/metanorma/repositories?q=template[Metanorma GitHub] repositories to check availability. +tag::template-steps[] +. Open a new terminal window on your computer. +. Use the `cd` command to navigate to the folder where the documents should be copied to. +. To copy the template to your machine, use the `new` command and specify the organization type and document. ++ +`metanorma new PROJECT-NAME -t ORGANIZATION -d DOCUMENT-TYPE` ++ +These examples illustrate how to use `metanorma new` in different setups: ++ +.Local Metanorma installation +[%collapsible] +====== +[source] +==== +`metanorma new my-new-standard -t ogc -d standard` +==== +====== ++ +.Metanorma in Docker (MacOS) +[%collapsible] +====== +[source] +==== +`docker run -v "$(pwd)":/metanorma/ -w /metanorma metanorma/metanorma metanorma new my-new-standard -t ogc -d standard` +==== +====== ++ +.Metanorma in Docker (Windows) +[%collapsible] +====== +[source] +==== +`docker run -v "%cd%":/metanorma/ -w /metanorma metanorma/metanorma metanorma new my-new-standard -t ogc -d standard` +==== +====== + +. Edit the copied files with a text editor of your choice. + +The Metanorma link:/_posts/2019-04-26-metanorma-templates-and-metanorma-new.adoc[blog post about templates] discusses the technical details of templates. +end::template-steps[] +== How to import a Word document +Before you can import Word files, you need to install: + +* https://www.libreoffice.org/[Libre Office] v5 +* Word2AsciiDoc tool + +.Installing the Word2AsciiDoc tool +[source, shell] +==== +sudo gem install reverse_adoc +==== + +. Open a new terminal window on your computer. +. Use the `cd` command to navigate to the folder containing the word documents to be converted. +. Run the following command, specifying the original Word file and the name of the AsciiDoc file: ++ +[source, shell] +==== +w2a input.docx -o output.adoc +==== + +The Word2AsciiDoc tool is still in development. Please refer to the https://github.com/metanorma/reverse_adoc[Reverse AsciiDoc Github repository] for all technical details. + +=== Organizing your project + +After creating your Metanorma document, decide how you want to organize your files. Our best practice guidance helps you decide what strategy fits for your project. +//LINK to BEST PRACTICE: PROJECT ORGANIZATION diff --git a/author/topics/document-format/meta-attributes.adoc b/author/topics/document-format/meta-attributes.adoc deleted file mode 100644 index e8baa5ff..00000000 --- a/author/topics/document-format/meta-attributes.adoc +++ /dev/null @@ -1,98 +0,0 @@ ---- -layout: author-docs ---- - -== Document attributes - -Metadata of a standard is entered as document attributes in Metanorma. - -Document attributes are also used to adjust some aspects of document generation -process and visual appearance of output documents. - -Some of the attributes are simple flags, while others expect a value to be -provided. - -Document attributes are supplied in the document header. - -[source,asciidoc] -.Document header example ----- -= Rice model <1> -:docnumber: 17301 <2> -:tc-docnumber: 9999 -:partnumber: 1 -:draft: -:edition: 2 -:copyright-year: 2016 -:language: en -:mn-document-class: iso -:mn-output-extensions: xml,html,doc,pdf <3> -:local-cache-only: <4> -:data-uri-image: ----- -<1> Title of the document. -<2> In Metanorma-ISO, the `:docnumber:` attribute specifies the document number, which is the value _17301_ here. -<3> Some attributes allow multiple values, which is comma-delimited -<4> `:local-cache-only:` demonstrates a kind of attribute that works without a value - (the attribute itself is either present or not, Boolean style) - -The order of attributes does not matter to Metanorma. - - -=== Which attributes to specify? - -The attributes required or allowed to be specified for given document -depend on the type of document and the Metanorma flavor used. - -See link:/author/ref/document-attributes/[generic attribute reference] -for attributes supported by most Metanorma flavors. - -When using one of the officially supported Metanorma flavors, -please consult your flavor's author documentation. - - -=== Re-using attributes in text - -The body of the document can reference the values of document attributes. -Here's an example of referencing committee-related metadata entries: - -[source,adoc] ----- -:technical-committee-number: 184 -:technical-committee: Automation systems and integration -:subcommittee-number: 4 -:subcommittee: Industrial data -... - -This document was prepared by Technical Committee ISO/TC -{technical-committee-number}, _{technical-committee}_, Subcommittee SC -{subcommittee-number}, _{subcommittee}_. ----- - -If the corresponding document attributes are not populated in the header, then -the references themselves will not be populated. - - -=== Dealing with Unicode characters - -Document attribute values that contain Unicode characters must be entered -directly as Unicode. - -Any non-ASCII characters in document attribute values, or dashes for compound -titles, will need to be entered as Unicode. - -As an example, this would work: - -[source,adoc] --- -:title-part-en:Information Technology—Security -:title-main-fr: Spécification et méthodes d'essai --- - -Entering them as HTML Entities or XML Entities would not: - -[source,adoc] --- -:title-part-en:Information Technology\—Security -:title-main-fr: Sp\écification et m\éthodes d'essai --- diff --git a/author/topics/document-format/page-flow.adoc b/author/topics/document-format/page-flow.adoc new file mode 100644 index 00000000..6ee803c3 --- /dev/null +++ b/author/topics/document-format/page-flow.adoc @@ -0,0 +1,115 @@ +--- +layout: author-docs +title: Page flow +--- += Page flow + +== Page breaks and orientation + +=== General + +Page breaks can be given a page orientation, which applies from that +point forward until the next page break with a page +orientation [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.17]. + +Page orientation only appears in paged output, such as in Word. + +To set content to landscape mode, the syntax is: + +[source,asciidoc] +-- +[%landscape] +<<< +-- + +To set content to portrait mode, the syntax is: + +[source,asciidoc] +-- +[%portrait] +<<< +-- + +If no orientation option is given, the text after the page break +remains in the same orientation as that before. In Word, page breaks +changing orientation are realised as distinct sections. + +In Metanorma, documents are split into three sections by default: + +* a cover page, +* a preface, and +* the main document body (including annexes and bibliography) +* (some documents also have a colophon) + +The page orientation is reset at the start of the main document body to `portrait`. + +[example] +.Example of switching from portrait to landscape and back to portrait in the same document +==== +[source,asciidoc] +-- +// Content following this directive will be shown in landscape mode +[%landscape] +<<< + +... + +// Content following this directive will return to portrait mode +[%portrait] +<<< + +... +-- +==== + +=== Avoiding page breaks + +The "`keep with next`" feature is useful if you want to indicate that +a document element must belong on the same page with another element, +on a paginated +medium [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.4.1]. + +NOTE: "`Keep with next`" is often considered as the opposite of a forced +"`page break`", i.e. a "`page unbreak`". + +Metanorma supports the following boolean attributes for the avoidance +of page breaks: + +`keep-with-next`:: The block with this attribute specified will be rendered +on the same page with the next document element. + +`keep-lines-together`:: The block with this attribute specified will force +the paragraph to render all its content on the same page. + +The syntax is as follows: + +[source,asciidoc] +-- +[keep-with-next=true] +{Paragraph or block} +-- + +and + +[source,asciidoc] +-- +[keep-lines-together=true] +{Paragraph} +-- + +The following syntax indicates that these two paragraphs will always be +presented on the same page, even if the textual layout allows them to be +split into two pages. + +[example] +.Example of using keep-with-next to avoid page breaks +==== +[source,asciidoc] +-- +[keep-with-next=true] +This is a paragraph. + +This is a paragraph that will be on the same page as the +immediately previous one. +-- +==== diff --git a/author/topics/document-format/sections.adoc b/author/topics/document-format/sections.adoc deleted file mode 100644 index 1f7cdbd9..00000000 --- a/author/topics/document-format/sections.adoc +++ /dev/null @@ -1,535 +0,0 @@ ---- -layout: author-docs ---- - -= Document sections - -Sections are marked off in AsciiDoc with titles prefixed by at least two equal signs, `==`. - -* `===` indicates a first level subsection; -* `====` a second level subsection; -* and so on. - -== Clause headings - -=== Fixed section names - -Metanorma relies on certain pre-defined section titles -to identify the different kinds of sections in the document, namely these: - -* `Misc-Container` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7] -* `Abstract` -* `Foreword` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] -* `Introduction` -* `Acknowledgements` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] -* `Scope` -* `Normative references` -* `Terms and definitions` -* `Symbols and abbreviated terms` -* `Symbols` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] -* `Abbreviated terms` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] -* `Bibliography` - -[NOTE] -==== -The above section titles as detected by Metanorma are case-insensitive. -While ISO Directives Part 2 demands clause titles to be in -https://en.wikipedia.org/wiki/Letter_case#Sentence_case[sentence case], -some organizations utilize -https://en.wikipedia.org/wiki/Letter_case#Title_case[title case]. -==== - -[NOTE] -==== -A dedicated topic link:../section-terms/[expands on "`Terms and definitions`" section grammar], specifically. -==== - -Fixed section names are specific to either the preface of a document, or the main body; -so for example an instance of "Introduction" the main body of the text will not be treated -as part of the preface. - -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. - -As an alternative -(if the document deviates from that naming structure, or is in a language other than English), -the section can be prefixed with a `heading=` attribute -that provides the English canonical form of the section name. For example: - -[source,asciidoc] --- -== Normative references - -[heading=terms and definitions] -== Terms, definitions and abbreviations --- - -=== Blank subclause headings - -Blank subclause headings can be given like this: - -[source,asciidoc] --- -=== {blank} --- - -These are used when you want to give a subclause number for a new subclause, -but without an associated header text. For example, - -[source,asciidoc] --- -=== Physical and chemical characteristics - -==== {blank} - -The mass fraction of moisture, determined in accordance with... --- - -renders as - -____ -*4.2. Physical and chemical characteristics* - -*4.2.1.* The mass fraction of moisture, determined in accordance with... -____ - -[NOTE] -==== -This notation should not be used to implement paragraph numbering as required for e.g. metanorma-un. -The link:/flavors/un/[UN Metanorma flavor] treats each paragraph -as a distinct clause and automatically numbers it. -==== - -=== Inline headings - -Inline subclause headings (e.g. for test methods) are indicated by preceding the heading -with the `[%inline-header]` option attribute. So in the Rice Model document, - -[source,asciidoc] --- -[%inline-header] -==== Sieve, - -with round perforations of diameter 1,4 mm. --- - -renders as - -____ -*A.2.1.1. Sieve,* with round perforations of diameter 1,4 mm. -____ - -=== Variant titles - -Variant titles [added in -https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5] are entered -as paragraphs with a `variant-title` role attribute within a clause, as follows: - -[source,adoc] ----- -=== Proper title - -[.variant-title,type=sub] -This is the variant title - -Text of section. ----- - -Variant titles of type `sub` are rendered as subtitles of clauses. - -=== Floating titles - -WARNING: Intended for legacy support only. Use with care. - -A "`floating title`" is a title that is placed outside the numbered hierarchy of -clauses. This means that a floating title is not uniquely referable like normal -clauses. - -Since the hierarchical structure of standards documents is critical to their -proper referencing, floating titles are commonly disallowed by standards -documents. Nonetheless, for legacy support reasons, floating titles are -supported in Metanoma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.4]: - -[source,adoc] ----- -=== Section 2.1 - -[discrete] -==== I am a floating title within section 2.1 - -==== Section 2.1.1 ----- - -NOTE: Floating titles are sometimes referred in AsciiDoc as "`discrete titles`". - - -== Clause attributes - -=== Language & script - -The language and script of a section is indicated via the optional attributes -`language` and `script`: - -[source,asciidoc] --- -[language=fr] -== Section 3 - -[appendix,script=Zmth] -== Math Appendix --- - -=== Obligations - -The obligation of a section—whether it is normative or informative—is indicated -via the attribute “obligation” (see example below). - -For most sections, this is fixed; for annexes and clauses, -the default value of the obligation is "normative" and users need to set the obligation -to "informative" as a section attribute if needed. For example: - -[source,asciidoc] --- -[[AnnexA]] -[appendix,obligation=informative] -== Determination of defects --- - -=== Numbering - -As with link:/author/topics/document-format/text#numbering-override[block element numbering], -a clause number may be provided to override auto-numbering. - -For instance, in order to number out-of-sequence clauses in updated -documents or amendments [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.3]. - -A manual clause number is specified with the attribute `number`: - -[source,asciidoc] ----- -== Clause 7 - -[number=0] -=== Zeroth Subclause ----- - -Elements subsequent to the manually numbered element will be auto-numbered -so as to follow the previous element. This may include incrementing the final -letter in an alphanumeric clause number (e.g. _7a_ followed by _7b_.) - -If resumption of auto-numbering is not intended for subsequent clauses -(e.g. _7bis_ should not be followed by _7bit_), -an explicit number also needs to be given to those clauses separately. - - -== Prefatory clauses - -=== Foreword - -A foreword is a full Metanorma AsciiDoc section, with the -title "`Foreword`"; this can be overruled in different flavours. - [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] -A foreword may contain subclauses. - -[source,asciidoc] --- -[[foreword]] -== Foreword -The Calendaring and Scheduling Consortium ("`CalConnect`") is a global non-profit -organization with the aim to facilitate interoperability of technologies across -user-centric systems and applications... - -=== Foreword subclause - -More foreword... --- - -[NOTE] -==== -Metanorma AsciiDoc also supports a simple foreword clause syntax, using the -AsciiDoc preamble (any text between the document header and the first section -header). This syntax is restrictive (it requires there to be no preceding -clauses and no subclauses), and is now deprecated. - -The example below specifies the `.Foreword` title to the foreword in the source. -(Strictly speaking, this is the caption of the first paragraph in the foreword, -but it is used as the foreword header since the Foreword must precede any -AsciiDoc section headers.) - -Metanorma will supply the "`Foreword`" title if no such title is given. - -[source,asciidoc] --- -[[foreword]] -.Foreword - -The Calendaring and Scheduling Consortium ("`CalConnect`") is a global non-profit -organization with the aim to facilitate interoperability of technologies across -user-centric systems and applications... --- -==== - -=== Arbitrary prefatory clauses - -Arbitrary prefatory clauses are allowed in some flavors, and are disallowed -but "`accepted`" for encoding in certain flavors for backwards compatibility reasons. - -NOTE: Most flavors specify requirements on preface sections. Most flavors specify -mandatory and optional preface sections, while some completely disallow arbitrary -preface sections. - -[example] -In ISO only the "`Foreword`" is allowed -- arbitrarily named -preface sections are prohibited, in accordance with ISO Directives Part 2. - - -Any section detected as the "`Foreword`", or labelled as "`Introduction`", -"`Acknowledgements`" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19], or -"`Abstract`", will be inserted into the document preface. - -Any other first-level clauses tagged with the role attribute -`[.preface]` are also moved into the document preface - [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19]. - -If these prefatory sections are provided, they will be displayed in the following default ordering: - -* "`Abstract`" -* "`Foreword`" -* "`Introduction`" -* Preface clauses. Any prefatory clauses that don't fit the other specially "`named`" sections will be placed here. -* "`Acknowledgments`" - -[example] -.Automatic rendering order for prefatory clauses -==== -This source: - -[source,asciidoc] --- -// tagged as the "`abstract`" -[.preface,heading=abstract] -== Executive summary - -Widget manufacture has proven profitable until recent times, when increased -competition has forced a reevaluation... - -// tagged as the "`acknowledgements`" -[.preface,heading=acknowledgements] -== Organizational contributors - -The following organizations have contributed valuable resources and expertise -for the completion of this standard... - -// tagged as normal -[.preface] -== Note for draft - -This is not an international standard, please be aware of the responsibilities -that come with application of this document... --- - -Will be rendered in this order despite the input order: - -* "`Executive summary`" -* "`Note for draft`" -* "`Acknowledgments`" -==== - -[[misc-container]] -=== Misc-Container - -The `misc-container` element in Metanorma XML contains miscellaneous data necessary for the processing -of the document, that are not themselves part of the document. Examples include the https://www.unitsml.org/[UnitsML] -definitions of units referenced in the document, or identifiers used as aliases of anchors in the document. - -If a preface clause is named `Misc-Container` (case-insensitive), its contents are appended to the -`misc-container` element for the document [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. -This can be used to add data into a document that is not to be rendered, but which is still needed for processing. - -== Symbols and Abbreviations - -Symbols and Abbreviations sections are expected to be simple definition lists -(http://asciidoctor.org/docs/user-manual/#labeled-list["`labelled lists`"] -in AsciiDoc nomenclature). - -Metanorma takes care of sorting the symbol entries in the order prescribed by ISO/IEC DIR 2, -provided the symbols are in AsciiMath; sorting MathML and LaTeX entries is not currently supported. - -== Annexes - -All annexes must be preceded by the style attribute `[appendix]`, or -([added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.27]) -the role attribute `[.appendix]`. The latter can be used to combine the appendix. -with another style attribute, such as `[bibliography]`, though this is not recommended -practice. - -Like all clauses, annexes are **normative by default**, -an informative annex is indicated with `[appendix,obligation=informative]`. - -The **numbering** of annexes and appendices is automatic: -do not insert "Annex A" or "Appendix 1" as part of the title. - -Annex and Appendix **titles** can be left blank, as with Clauses. - -=== Term Annexes, Symbols Annexes, Bibliography Annexes - -Normally in Metanorma, the sections describing terms and definitions, symbols -and abbreviated terms, and bibliographic references are contained in a main -clause. - -However, it is possible for such clauses to be contained in annexes instead. In -fact, this is done by default for the "Terms and References" section in the NIST -flavour of Metanorma. - -In rendering, these annexes are treated identically as when those sections were -in the main body. - -However, the Metanorma information model does not permit a clause to be an annex -and a terms or a bibliographic clause at the same time. - -Such clauses are modelled as an annex *containing* a terms clause or bibliographic clause: - -[source,asciidoc] ----- -[annex] -== Bibliography - -[bibliography] -=== Bibliography ----- - -In order to render such annexes as expected, the following rules are -applied [added in https://github.com/metanorma/isodoc/releases/tag/v2.0.9]: - -* If an annex contains multiple subclauses, it is rendered as usual. -* If an annex contains a single subclause, and that subclause is a Terms & Definitions, -Symbols & Abbreviated Terms, or Bibliographic section, -** The title for that subclause is skipped in rendering -** The subclause itself is skipped for the purposes of numbering; if it has any sub-subclauses -of its own, they are numbered as immediate child clauses of the annex. - -So: - -[source,asciidoc] ----- -[annex] -== Terminology - -=== Terms and definitions - -==== First Term - -==== Second Term ----- - -is rendered like - -____ -*Annex A. Terminology* - -*A.1 First Term* - -*A.2 Second Term* -____ - - -== Sections deeper than 5 levels - -Standards can contain many levels of embedding: ISO/IEC DIR 2 only considers -it a problem if there are more than 7 levels of embedding. - -To realise higher levels of embedding, -prefix a 5-level section title with the attribute `level=`: - -NOTE: Asciidoctor AsciiDoc permits only five levels of section embedding -(not counting the document title). - - -[source,asciidoc] --- -// Six equal signs for five levels -====== Clause 5A - -[level=6] -====== Clause 6A - -[level=7] -====== Clause 7A - -[level=7] -====== Clause 7B - -[level=6] -====== Clause 6B - -====== Clause 5B --- - -This generates the following ISO XML: - -[source,xml] --- - - - Clause 5 - - - - Clause 6 - - - - Clause 7A - - - - - Clause 7B - - - - - - Clause 6B - - - - - - Clause 5B - - --- - -and the rendering would be something like - -*1.1.1.1.1 Clause 5A* - -*1.1.1.1.1.1 Clause 6A* - -1.1.1.1.1.1.1 Clause 7A - -1.1.1.1.1.1.2 Clause 7B - -*1.1.1.1.1.2 Clause 6B* - -*1.1.1.1.2 Clause 5B* - - -== Table of Contents - -The table of contents is generated automatically for Word, HTML, and PDF output. - -* In Word, it takes the form of a normal Word Table of Contents; the page numbers -are not populated when the document is generated, and the table of contents needs -to be refreshed (Right Click: Update Field). -* In HTML, it takes the form of a side panel. In PDF, it takes the form of an -introductory table of contents; because the PDF is generated from HTML in Metanorma, -there are no page numbers in the table of contents. - -By default, the table of contents includes two levels of heading. More levels of -heading can be set by using the document attribute `:toclevels:`; e.g. -`:toclevels: 3` for three levels of heading included. The number of levels of heading -to include can be set separately for HTML/PDF and for DOC, by using the document -attributes `:htmltoclevels:` and `:doctoclevels:`. - diff --git a/author/topics/document-format/text.adoc b/author/topics/document-format/text.adoc index bd5dffbd..e5c3f215 100644 --- a/author/topics/document-format/text.adoc +++ b/author/topics/document-format/text.adoc @@ -93,14 +93,42 @@ renders: image::/assets/author/topics/document-format/text/fig-underline.png[Illustration of underlined text in Metanorma] ==== +=== Ruby +Ruby annotations in East Asian text are provided [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.5] +using the `ruby:{annotation}[{base text}]` macro, with optional paramters +`lang=` for language of annotation, `script=` for script of annotation, and `type=` for the type of annotation +(`pronunciation` or `annotation`, with `pronunciation` as the default value): + +[source,asciidoc] +---- +ruby:とうきょう[東京] +ruby:とうきょう[lang=ja,script=Hira,type=pronunciation,東京] +ruby:Tōkyō[type=pronunciation,script=Latn,東京] +ruby:ライバル[type=annotation,親友] +ruby:とう[東] ruby:きょう[京] +ruby:Tō[script=Latn,東]ruby:kyō[script=Latn,京] +---- + +Metanorma supports "double-sided" Ruby annotations, with annotations both above and below characters; these are marked up as nested +Ruby annotation macros, with the deeper nested annotation assumed to be the annotation below the characters. + +[source,asciidoc] +---- +ruby:とう[ruby:tou[東\]] ruby:なん[ruby:nan[南\]] の方角 +ruby:たつみ[ruby:とう[東\]{blank}ruby:なん[南\]] +ruby:プロテゴ[ruby:まも[護\]{blank}れ]! +ruby:プロテゴ[れ{blank}ruby:まも[護\]]! +---- + +As of this writing, double-sided annotations are not supported in Word, and the nested annotations are realised as bracketed text. + + +[[css]] === CSS declarations The `css` command is used to wrap content with a CSS declaration -(https://developer.mozilla.org/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration[MDN]) -[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6]. - -This feature only applies to HTML output. +(https://developer.mozilla.org/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration[MDN]) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6]. NOTE: CSS declarations are also used within the HTML `style` attribute. @@ -128,6 +156,65 @@ Where: -- ==== +NOTE: Any font specified in `[css font-family:...]` needs to be passed to Metanorma for processing +by specifying it in the `:fonts:` document attribute. + +=== Capitalisation + +Capitalisation may be applied automatically in the rendering of documents, despite not being present in the source material; +for example, titles and captions may be title-cased or put in all caps. In order to prevent a span of text automatically +having its case changed, use CSS styling to set its CSS text-transform property to "none" [added in https://github.com/metanorma/isodoc/releases/tag/v2.8.5]: + +[example] +.Example of a word in a title not to be capitalised +==== +[source,asciidoc] +-- +:title: [css text-transform:none]#IoT# and content standards + +... + +=== Approaches to [css text-transform:none]#IoT# +-- +==== + +As shown, such styling extends to document titles as document attributes. + +=== Custom character sets + +When a https://en.wikipedia.org/wiki/Private_Use_Areas[private use codepoint] +is used in a document, reflecting an agreement between the document author +and the document renderer, but *not* a standard like Unicode, the custom character set that includes +that codepoint needs to be flagged. So U+F8D0 is the Klingon letter for "a" in the +https://www.evertype.com/standards/csur/[Conscript Unicode Registry], but the Kanji-Katakana hybrid of +訁and コ (equivalent to 講) in the https://www.babelstone.co.uk/Fonts/PUA.html[BabelStone PUA]. + +In order to flag such a custom interpretation of the codepoint, the interpretation can be named +in a formatting directive, flagged as `custom-charset` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.3]. +For example: + +[source,asciidoc] +---- +[custom-charset:conscript]#\\uf8d0# +[custom-charset:babelstone]#\\uf8d0# +---- + +In order to be rendered, a font implementing that interpretation needs to be indicated as a processing hint +for Metanorma. This is done with the Presentation XML metadata directive +`:presentation-metadata-custom-charset-font: {name of interpretation}:"{name of font}"`, as a document attribute, +giving a comma-delimited list of charset-font pairs. For instance: + +[source,asciidoc] +---- +:presentation-metadata-custom-charset-font: conscript:"Code 2000",babelstone:"BabelStone PUA" +:fonts: "Code 2000","BabelStone PUA" +---- + +As with link:/author/topics/document-format/text#css[CSS declarations], +any font specified as a custom charset font also needs to be passed to Metanorma +in the `:fonts:` document attribute. + +== Semantic elements === Identifier @@ -208,6 +295,48 @@ rendering. NOTE: Only certain Metanorma flavors support enhanced rendering for semantically-tagged content. +The semantic label is realised in Metanorma as a `class` attribute. That means +that distinct rendering of spans can be specified by embedding +link:/author/topics/document-format/sections#user-css[custom CSS] +in the Metanorma document, with CSS classes matching the span: + +[source,asciidoc] +----- +== Metanorma-Extension + +=== user-css + +[source] +---- +.green { background-color: green} +---- + +.... + +span:green[this text is highlighted as green] +----- + +=== Dates + +The `date` command is used to introduce dates and date-times as semantic +elements [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.5]. +The value of the `date:[]` macro is an ISO-8601 formatted date or date-time. +The second argument given in the macro, if present, is a +https://ruby-doc.org/stdlib-3.0.0/libdoc/date/rdoc/DateTime.html#method-i-strftime[`strftime` formatting description +of the date]. (Space can be specified as `%_`.) +Month and day names and abbreviations, if requested in the formatting string, are internationalised +to the document language. + +[source,asciidoctor] +---- +date[2012-02-02] +date[2012-02-02, %F] +date[2012-02-02, %A %d %B] # Thursday 2 February +date[2012-02-02T21:04:05, %F%_%l%_%p] +---- + +== Other + === Nesting of styles @@ -292,6 +421,19 @@ This will render the following links depending on the output format: * in PDF, `../parent.pdf` and `../child.pdf` ==== +=== Hyperlink validation + +Hyperlinks are validated and normalised +in Metanorma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.5.2]. +Hyperlinks are treated as IRIs (internationalised resource identifiers -- i.e. non-ASCII +Unicode characters are allowed.) + +As with Asciidoctor, http(s) links are assumed by default to be intended as hyperlinks, +and are marked up and rendered as such. Example hyperlinks are often invalid (e.g. +`http://{domain}`), and Metanorma execution will be aborted if they are found, since they +cannot be rendered as meaningful hyperlinks. Such links should be escaped by prefixing them +with a backslash, which will result in them being treated as plain text (e.g. `\http://{domain}`.) + === Numeric ranges @@ -491,6 +633,21 @@ immediately previous one. -- ==== +== Column breaks + +Some Metanorma flavours apply column formatting to document texts. As of this writing, +this applies to BSI in PDF. For such texts, it can be useful to specify a column break +to be observed in rendering, rather than let the end of the column by determined automatically. +To that end, Metanorma supports a column break directive [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.2]. +This directive needs to appear on a separate paragraph on its own: + +[source,asciidoc] +-- + +columnbreak::[] + +-- + == Block quotes @@ -540,7 +697,7 @@ image::/assets/author/topics/document-format/text/fig-block-quote.png[Illustrati === Folding notes -Notes that are not at the end of a clause are folded into the preceding block, +Notes are folded into the preceding block, if that block is not delimited (so that the user could not choose to include or exclude a note). That is, notes are folded into a preceding list, formula, figure, or table. @@ -630,9 +787,6 @@ Bibliographic note === General -Admonitions ("`NOTE`", "`IMPORTANT`", "`WARNING`", "`CAUTION`" etc.) -are typically inserted into the main content of a document providing -guidance or request readers to exercise caution. [source,asciidoc] ---- @@ -661,6 +815,32 @@ This notice must not be ignored. ==== ---- +=== Types + +All five built-in Asciidoctor admonition types are recognised by Metanorma: + +* `[NOTE]` (which is treated as a Metanorma Note) +* `[TIP]` +* `[IMPORTANT]` +* `[CAUTION]` +* `[WARNING]` + +In addition, the following types are recognised by specifying `[type=...]` as +a block attribute on one of the latter four built-in admonition types in block mode (other than NOTE): + +* `statement`: typographically separate statements in mathematics, such as propositions, proofs, or theorems. +* `editorial`: annotation by document editors, intended for all readers of the document and not just its authors. +* `box`: box element, intended as standalone sidebar which can be referenced from within the document. + +[source,asciidoc] +---- +[TIP,type=box] +==== +This is a box +==== +---- + +Other types can also be entered. === Whole document admonitions @@ -944,6 +1124,39 @@ The following syntax will be processed as generating equal width columns. NOTE: In typical AsciiDoc, `[cols="3"]` is considered a shorthand to `[cols="1,1,1"]`, but this is not supported in Metanorma AsciiDoc. +For long tables that need to continue onto the next page in the DOC or PDF rendering of a document, +Metanorma, by default, will automatically repeat the header after every page break. +To suppress this behavior, you can apply the `noheader` value to the `options` attribute +using its formal (`options=noheader`) or shorthand (`%noheader`) syntax. +There is a caveat that this option will also deactivate the implicit assignment of the +header to the first row of the table +(see link:https://docs.asciidoctor.org/asciidoc/latest/tables/add-header-row/#implicitly-assign-header-to-the-first-row[Implicitly assign header to the first row]). +Therefore, you will need to apply the header tag (`h|`) to every cell of the first +row to define it as the header. + +=== Table sources + +A table can incorporate an indication of its source, +which in Metanorma is expected to be a bibliographical reference, just as with +term sources [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2]. +Any such sources need to appear after the table, and before any notes which will also be +included in the table. + +[source,asciidoc] +-- +|=== +| Head | Head + +| Row | Row +|=== + +[.source] +<>, reformatted + +NOTE: Note 1 + +NOTE: Note 2 +-- == Mathematical expressions @@ -1015,6 +1228,22 @@ f -= lambda x (a * x + b) WARNING: Some math expressions are NOT supported by AsciiMath. In that case it is necessary to use LaTeX math or MathML input. +[WARNING] +.Encoding brackets inside stem:[] +==== +When we encode inline math expressions that contain brackets we have have to +make sure of two things: + +. The closing bracket must be escaped, `\]`. + +. If the opening bracket is the first character of the expression, there should be +a white space between `stem:[` and the opening bracket; i.e. `stem:[ [...`. +Otherwise, the engine may interpret the double-opening brackets `[[` as the +beginning of an anchor definition. + +As an example, suppose we want to encode this inline expression: stem:[[x_n,y_n\]]. + +The correct encoding to avoid misinterpretations would be: `\stem:[ [x_n,y_n\]]` +==== === Using LaTeX math @@ -1224,6 +1453,31 @@ stem:[m_S]:: is the mass, in grams, of the test sample. == Figures +=== Blocks + +An image block in isolation is treated as a figure: + +[source,asciidoc] +-- +.Figure title +image::figure-path.png[] +-- + +A more complex figure can be marked up as an example block, with the `[figure]` style attribute: + +[source,asciidoc] +-- +[figure] +.Figure title +==== +image::figure-path.png[] + +This is some random explanatory text + +NOTE: And this is a note +==== +-- + === Key Like formulae, figures can be followed by a definition list for the variables used in the figure. @@ -1397,6 +1651,9 @@ image::logo.jpg[] -- ==== +Image sizes can also be specified with percentages of the original width, +e.g. `width='50%'` [added in https://github.com/metanorma/isodoc/releases/tag/v2.8.0]. + NOTE: Treatment of image resizing may slightly differ across output formats. @@ -1460,7 +1717,7 @@ For accessibility, preformatted blocks can be provided with an `alt` text attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10]. [sources,asciidoc] --- +---- [alt=ASCII art of a dog] .... ___^_ @@ -1471,7 +1728,7 @@ attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/ / ___ 0 | / / \___ _/ .... --- +---- === Figure classes @@ -1487,6 +1744,23 @@ through the `class` attribute [added in https://github.com/metanorma/metanorma-s image::logo.jpg[] -- +=== Figure sources + +When a figure is marked up as a block, it can incorporate an indication of its source, +which in Metanorma is expected to be a bibliographical reference, just as with +term sources [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.2]. + +[source,asciidoc] +-- +[figure] +.Rice husk separation +==== +image::logo.jpg[] + +[.source] +<>, reformatted +==== +-- == Passthrough to Metanorma XML and target formats @@ -1600,7 +1874,11 @@ pass-format:FORMAT[...] Where: -* `FORMAT` is a comma-delimited list of target formats. +* `FORMAT` is a comma-delimited list of target formats. The formats known to Metanorma are: +`html`, `doc`, `pdf`, `sts` (STS XML), `ieee` (IEEE XML), `rfc` (RFC XML v3), `txt`, `html_alt` (for ISO), +`isosts` (ISO STS XML) +* Metanorma will also accept the value `all` +(all possible formats) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.3]. [example] .Example of specifying passthrough for selected target formats @@ -1611,6 +1889,8 @@ pass-format:rfc[ᏚᎢᎵᎬᎢᎬᏒ] -- ==== +NOTE: Text that is marked up as pass-format is not subject to substitutions such as smart quotes. +It can be used to keep straight quotes in a document that otherwise uses smart quotes. == Source code @@ -1651,35 +1931,21 @@ It is possible to specify the computer language used in the `[source]` block to enable source code highlighting (syntax highlighting) for supported languages. -Metanorma integrates the http://coderay.rubychan.de[CodeRay syntax highlighter] -which supports the following list of languages represented by codes: - -* `c` -* `clojure` -* `css` -* `delphi` -* `diff` -* `erb` -* `go` -* `groovy` -* `haml` -* `html` -* `java` -* `java_script` -* `json` -* `lua` -* `php` -* `python` -* `raydebug` -* `ruby` -* `sass` -* `sql` -* `taskpaper` -* `xml` -* `yaml` - -NOTE: The full list of supported file extensions is provided by https://github.com/rubychan/coderay/blob/c25e8ef53cef6e72b98547139a6a27bdd4f1aaf3/lib/coderay/helpers/file_type.rb#L79-L131[CodeRay]). +Metanorma integrates the +https://github.com/rouge-ruby/rouge[Rouge syntax highlighter] +which applies to all of HTML, DOC, and PDF output [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2]. +(Before that date, it used the client-side https://github.com/googlearchive/code-prettify[Google Code Prettify], +which only applied to HTML output.) +Syntax highlighting is enabled by default; it is turned off through the document attribute +`:source-highlighter: false` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2]. + +The full list of languages supported is given in https://rouge-ruby.github.io/docs/file.Languages.html[Rouge Languages], +with the language names that Rouge recognises; e.g. _Literate CoffeeScript_ is specified as `literate_coffeescript`. + +Line numbering can optionally be specified for a source code snippet through the `%linenums` option +(i.e. by entering `[source%linenums,...]` instead of just `[source,...]` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2]. It can be enabled by default for code snippets through the document attribute `source-linenums-option: true`. +Line numbering requires syntax highlighting to be enabled. [source,asciidoc] -- @@ -1690,11 +1956,11 @@ Rendered in monospace with syntax highlighting -- [example] -.Example of rendering source code with language specification and syntax highlighting +.Example of rendering source code with language specification, line numbering, and syntax highlighting ==== [source,asciidoc] -- -[source,ruby] +[source%linenums,ruby] ---- class MyIdentifier def format(string) @@ -1855,6 +2121,21 @@ of `image1.gif`; that instructs any downstream processing that extracts images out of the file (such as `metanorma -e`) to extract this image to the file `image1.gif`, instead of using an automatically generated filename. +== Columns + +Metanorma has limited support for rendering text in multiple columns. (As of this writing, +it is limited to BSI, and PDF output only.) Where text is rendered in multiple columns, +it is possible to override the rendering of individual blocks, with a `columns` attribute, +setting the count of columns that they should be rendered with instead [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.0]: + +[source,asciidoc] +---- +[columns=1] +____ +This blockquote spans all columns of the text +____ +---- + == Auto-numbering === General @@ -1942,7 +2223,7 @@ E (3) ____ ==== - +// tag::unnumbered[] === Unnumbered elements Sometimes a document element needs to be excluded from auto-numbering. @@ -2048,6 +2329,21 @@ stem:[forall v_{i}] *bounce* stem:[v_{i}] off the wall -- ==== +Numbering can be suppressed for all instances of a Metanorma XML block type +throughout a document, through the document attribute `:block-unnumbered:`, +which takes as its argument a comma-delimited list of Metanorma XML block +names [added in https://github.com/metanorma/isodoc/releases/tag/v2.4.6]: + +[source,asciidoc] +---- +:block-unnumbered: sourcecode, figure +---- + +A block instance will remain numbered if it is explicitly set to +`unnumbered=false`, or if it has a manually set anchor (recognised as not +prefixed with an underscore --- `[[_anchor]]` will be ignored) [added in https://github.com/metanorma/isodoc/releases/tag/v2.4.9]. + +// end::unnumbered[] === Prevention of double-numbering diff --git a/author/topics/document-format/xrefs.adoc b/author/topics/document-format/xrefs.adoc index c2378da1..e31a0ab3 100644 --- a/author/topics/document-format/xrefs.adoc +++ b/author/topics/document-format/xrefs.adoc @@ -53,7 +53,7 @@ in the AsciiDoc source (e.g. `\<<``formulaB-1``>>` generates either "`Formula (B.1)`" or "`B.6, Formula (B.1)`", depending on where in the document it occurs.) - +[[xref-styles]] == Cross-reference styles Metanorma supports multiple cross-reference styles [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.6]. @@ -297,13 +297,13 @@ both prevent URIs from being used themselves as document anchors. In order to specify the aliases of anchors manually, you will need to specify a table with anchor `_misccontainer_anchor_aliases` under the -(link:/author/topics/document-format/section#misc-container[`Misc-Container` clause]) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. +(link:/author/topics/document-format/section#misc-container[`Metanorma-Extension` clause]) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. Each row of that table will have the anchor as its first cell, and aliases of the anchor as the other cells; there can be more than one alias of an anchor. [source,asciidoctor] ---- -== Misc-Container +== metanorma-extension [[_misccontainer_anchor_aliases]] |=== @@ -381,6 +381,19 @@ http://www.example2.com[text to go into the second hyperlink,title=This is a too -- ==== +Hyperlinks can also have a rendering style set with a flavour-specific value [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.1]; +this option is currently only used in IETF. This is specified by appending `,style=...` after the text in the URL macro: + +[example] +==== +[source,adoc] +-- +http://www.example.com[style=brackets] + +http://www.example2.com[text to go into the hyperlink,style=brackets] +-- +==== + == External references In link:/author/topics/document-format/bibliography#localities[localities and locality values], diff --git a/author/topics/inline_markup.adoc b/author/topics/inline_markup.adoc new file mode 100644 index 00000000..27de2dda --- /dev/null +++ b/author/topics/inline_markup.adoc @@ -0,0 +1,13 @@ +--- +layout: author-docs +title: Inline Markup +--- +tag::tutorial[] +To annotate single words, you use inline markup. The markup encloses the word(s) and you do not need to begin a new line. Inline markup allows you to: + +* Emphasize text +* Link to external resources with hyperlinks +* Create internal cross-references +* Create index entries +* Create Bibliographic entries +end::tutorial[] \ No newline at end of file diff --git a/author/topics/document-format/changes.adoc b/author/topics/inline_markup/changes.adoc similarity index 95% rename from author/topics/document-format/changes.adoc rename to author/topics/inline_markup/changes.adoc index fbdea7cf..4a93dee5 100644 --- a/author/topics/document-format/changes.adoc +++ b/author/topics/inline_markup/changes.adoc @@ -1,5 +1,6 @@ --- layout: author-docs +title: Machine-readable changes --- = Machine-readable changes @@ -119,3 +120,4 @@ del:[The use of echo cancellers on the VBD channel, as per Rec. ITU-T G.168.] ... or other forms of redundancy add:[(e.g. per <>)] -- +For more complicated corrigenda involving changes, you may use link:/author/topics/document-format/annotation#reviewer[reviewer notes]. diff --git a/author/topics/inline_markup/footnotes.adoc b/author/topics/inline_markup/footnotes.adoc new file mode 100644 index 00000000..a5e0c9fc --- /dev/null +++ b/author/topics/inline_markup/footnotes.adoc @@ -0,0 +1,145 @@ +--- +layout: author-docs +title: Footnotes +--- +== General + +tag::tutorial[] + +Footnotes are useful for adding remarks to content without distracting from the +reading flow. + +Metanorma AsciiDoc supports: + +* inline footnotes +* multi-paragraph footnotes + +NOTE: Typical AsciiDoc does not support multi-paragraph footnotes. + + +== Inline footnotes + +Footnotes are added to a document using the footnote command (`footnote:[]`). + +The syntax is demonstrated as: + +[source,adoc] +---- +Oryza sativafootnote:[Sativa means "cultivated"], is rice that is farmed commercially. +---- + + +== Multi-paragraph footnotes + +The multi-paragraph footnote command `footnoteblock:[id]` allows for specification +of multi-paragraph content within a +footnote, through a named note block. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.4]. + +The `id` is the identifier of a note containing the contents of the footnote. + +The following syntax is used: + +[source,adoc] +---- +... footnoteblock:[my-anchor] ... <1> + +... +[[my-anchor]] <2> +[NOTE] <3> +-- +Multi-paragraph footnote content. +-- +---- +<1> `my-anchor` indicates where the footnote's text block is located. +<2> Anchor of the multi-paragraph NOTE block. +<3> Defined NOTE block that provides content for the footnote. + +.Example of a multi-paragraph footnote +==== +[source,adoc] +---- +This is a paragraph.footnoteblock:[id1] This continues the paragraph. + +[[id]] +[NOTE] +-- +This is + +a multi-paragraph + +footnote +-- +---- +==== + +NOTE: Multi-paragraph footnotes are a Metanorma AsciiDoc feature and not +supported in typical AsciiDoc. + +end::tutorial[] + + +== Named footnotes and duplicate footnotes + +In some cases, identical footnote content can apply to multiple places. +Metanorma AsciiDoc supports named footnotes that facilitate reuse without repeated +definitions. + +By default, Metanorma already detects whether footnote text is reused. +When the text of a footnote is repeated in two different places, the same +footnote number in both places, rather than treat the repetition as a new +footnote. Assignment of IDs is therefore optional. + +NOTE: Duplicated footnote reuse applies to HTML and DOC outputs. + + +The following syntax is used: + +[source,adoc] +---- +... footnote:{id}[text] ... <1> + +... footnote:{id}[] ... <2> +---- +<1> Definition of a named footnote. `{id}` is an assigned unique ID for the footnote, and `text` the footnote content +<2> To reuse a named footnote, specify the ID but keep the text portion empty. + + +.Example of a named footnote and its reuse +==== +[source,adoc] +---- +A bold statement!footnote:disclaimer[Opinions are my own.] + +Another outrageous statement.footnote:disclaimer[] +---- +==== + + + +== Special footnotes + +=== Table footnotes + +Footnotes immediately placed after a table are considered a "table footnote", +which renders the footnote at the table footer, within the table. + +A table footnote is numbered separately. + + +=== Figure footnotes + +Footnotes immediately placed after a figure are considered a "figure footnote", +which renders the footnote at the bottom of the figure. + +A figure footnote is numbered separately. + +=== Document title footnotes + +Footnotes on document titles are recognised [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.1], +but by default they are not rendered, because of how document title pages are +processed separately in Metanorma via Liquid templates. + +Document title footnotes are moved into `/bibdata/note[@type = +"title-footnote"]`, and are treated as document metadata, as are document titles +themselves. The location of the footnote within the title is not preserved. + diff --git a/author/topics/inline_markup/index_terms.adoc b/author/topics/inline_markup/index_terms.adoc new file mode 100644 index 00000000..4b8300ff --- /dev/null +++ b/author/topics/inline_markup/index_terms.adoc @@ -0,0 +1,217 @@ +--- +layout: author-docs +title: Index terms +--- + +=== General + +Metanorma supports index entries with primary, secondary and tertiary +index terms. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10]. + +Primary index terms are listed under the first-level index, +the secondary index terms are listed under the primary index terms' sub-index, +and the tertiary index terms are listed under the secondary index term's sub-index. + +.Illustration of an index in Metanorma with primary and secondary indexes are shown. +image::/assets/author/topics/document-format/text/fig-index.png[Illustration of an index in Metanorma with primary and secondary indexes are shown,width=70%] + +Index term behavior differs per rendered output format: + +* In PDF, indexes are rendered as references to page numbers. +* In HTML and DOC, indexes are rendered as references to the nearest + labelled block; a note, example, figure, formula etc., if the index + term is contained within it, or a clause or subclause, otherwise. + +Index term links are only rendered in certain flavours, and do not +appear otherwise in DOC, PDF or HTML output. + +NOTE: Currently, only the ISO, IETF and BIPM flavours render +index terms. + +NOTE: Metanorma always processes index terms and creates the corresponding XML. +However, not all flavors render an "Index" section. Check out the +link:/flavors/[flavor documentation] for your SDO to see if it supports +indexing. + + +=== Getting started + +tag::tutorial[] +Before you define an index term, your document needs a section where the index +terms can appear. To create an index, define a level 1 section (`==`) marked with +the style index at the end of your document. + +[source,adoc] +---- +[index] +== Index +---- + +Index entries can consist of up to three levels using a comma to separate the terms. + +Metanorma provides two options to create an index entry: + +* Visible index terms are words within the text that are annotated with an index +entry using double parentheses. `\((Level 1 index term))` + +* Hidden index terms are index entries that are not visible in the final output +and are generated using triple parentheses. +`(\((Level 1 index term, Level 2 index term, Level 3 index term)))`. +These allow the index to include optional subterms and sub-subterms; they also +allow the index term to differ from what actually appears in the text. + +Let's have a look at an example: + +[source,adoc] +---- +The Lady of the Lake, her arm clad in the purest shimmering samite, +held aloft Excalibur from the bosom of the water, +signifying by divine providence that I, ((Arthur)), <1> +was to carry Excalibur (((Sword, Broadsword, Excalibur))). <2> +---- +<1> `\((Arthur))` will be displayed as `Arthur` in the text and carries a first level index entry +<2> `(\((Sword, Broadsword, Excalibur)))` will not appear in the text, but a three level index entry will be generated. + +end::tutorial[] + + +=== Index placement + +If any index terms are present in a document, and the current flavour supports +indexes, then an index section will be automatically generated and appended to +the end of the document. + +To override the title of the index section, or indicate where it should be +placed, use the index section markup shown below. + +[source,adoc] +-- +[index] +== Index +-- + +Any index will be appended after any content you may choose to place in the +index section, but indexes typically appear with no preface. + + +[[auto-index-terms]] +=== Automated index terms + +If the document attribute `:index-terms:` is used, all terms (and symbols) are +indexed automatically in postprocessing. + +The document does not need to include explicit index terms for +them [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.3]. + + + + +=== Rendered index term syntax + +Metanorma index entries are entered through two different +syntaxes. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.10]. + +Rendered index term: `+((Term))+` + +* Produces the output "`Term`"; and +* Links to the primary index term of the same name, "`Term`". + +Hidden index term: `+(((IndexTerm1)))+`, +`+(((IndexTerm1, IndexTerm2)))+` or +`+(((IndexTerm1, IndexTerm2, IndexTerm3)))+` + +* Produces no output; and +* Links to the primary index term `IndexTerm1`. And if provided, links to + the secondary nesting, `IndexTerm2` and the tertiary nesting `IndexTerm3`. + +[example] +.Example of specifying rendered index term and hidden index terms +==== +[source,adoc] +-- +The Lady of the Lake, her arm clad in the purest shimmering samite, +held aloft Excalibur from the bosom of the water, +signifying by divine providence that I, ((Arthur)), +was to carry Excalibur (((Sword, Broadsword, Excalibur))). +-- +==== + +=== Rich-text formatting in index terms + +Rich-text formatting in index terms is +supported [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0]. + +[source,adoc] +-- +signifying by divine providence that I, ((*Arthur*)), +was to carry Excalibur (((Sword~E~, stem:[sqrt(E)], Excalibur))). +-- + +NOTE: Formatting of index terms is ignored in IETF rendering. + + +=== Entry ranges + +Metanorma supports index entries that involve +ranges [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0], +using the command `index-range:to[...]`. + +The command itself accepts an AsciiDoc index entry, such as +`+((...))+` or `+(((...)))+`. + +The index entry range starts at the location of the `index-range` +command, in the same way as the index command it contains; the end of +the range is the element with the anchor `to`, and that is expected +to be provided as a bookmark. + +[source,adoc] +-- +signifying by divine providence that I, index-range:end-range-1[((*Arthur*))], +was to carry Excalibur index-range:end-range-2[(((Sword~A~, stem:[sqrt(2)], Excalibur)))]. + +... + +and so forth.[[end-range-1]] + +... + +_Sic explicit fabula._[[end-range-2]] +-- + +The preceding example has a visible index entry for _**Arthur**_, +ranging from the location of `+*Arthur*+` up to `end-range-1`, and +a hidden index entry for _Sword~A~_, ranging from the location of +`+Sword~A~+` up to `end-range-2`. + + +=== Cross-references + +Metanorma also supports "`see`" and "`see also`" cross-references between +index terms [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.6.5], +using the `index` command. + +The command takes at least two parameters: + +* the primary index term to be cross-referenced; +* the target of the cross-reference; +* optionally, the secondary and tertiary index term to be cross-referenced. + +[source,adoc] +-- +index:see[Satchmo,Louis Armstrong] +index:see[James Brown,influences,Hank Ballard and the Midnighters] +index:also[guitar,electric,technique,Jimi Hendrix] +-- + +Rendered as: + +____ +* Satchmo, _see_ Louis Armstrong +* James Brown +** influences, _see_ Hank Ballard and the Midnighters +* guitar +** electric +*** technique, _see also_ Jimi Hendrix +____ + + diff --git a/author/topics/inline_markup/links.adoc b/author/topics/inline_markup/links.adoc new file mode 100644 index 00000000..6f9aa978 --- /dev/null +++ b/author/topics/inline_markup/links.adoc @@ -0,0 +1,133 @@ +--- +layout: author-docs +title: Adding links and cross-references +--- +tag::tutorial[] +References are an integral part of standards. The main mechanism for references are anchors and destinations. There are four types of references: + +* Hyperlinks to an external source, for example a link to a website +* Metadata references +* Internal references to a section, image, table, etc. +* link:author/topics/sections/entering-bib.adoc[Bibliographic entries] + +== Hyperlinks + +AsciiDoc lets you include links to external sources, and sources to files within the same project. + +To reference an *internal* source: + +. Use the https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro/[link macro] to include a link to a file. The syntax looks like this: `\link:PATH[]`. +. Add link text in square brackets after the path. ++ +.Example of an internal link +[source, AsciiDoc] +---- +Download the latest link:downloads/report.pdf[Report]! +---- +end::tutorial[] + +*Updating file extension automatically* + +Links to other Metanorma documents are expected to change their suffix depending on whether they are rendered as HTML, PDF, or DOC. + +To update file extensions automatically, add `updatetype=true` into the square brackets. +The link path must be https://www.w3schools.com/html/html_filepaths.asp[relative] and can not contain a file suffix. + +.Example of how to use the `updatetype` option +[source,asciidoc] +-- +link:../parent[updatetype=true] +link:../child[This Is The Child Document,updatetype=true] +-- + +This will link to `../parent.html` and `../child.html` in HTML, and to + `../parent.pdf` and `../child.pdf` in PDF. + +tag::tutorial[] +To reference an *external* source: + +. Paste the URL into the document. +. Add link text in square brackets after the URL (optional) `URL[Link text]`. ++ +.Example of an external link +[source, AsciiDoc] +---- +http://www.iso.org/[International Organization for Standardization]. +---- +end::tutorial[] +*Adding acessibility in URIs* + +To add acessibility URIs, use the `,title=...` option in the square brackets. +The option corresponds to HTML's alt text `a@title` attribute. + +[example] +==== +[source,asciidoc] +-- +http://www.iso.org[International Organization for Standardization,title=This is a tooltip for the link] +-- +==== + +tag::tutorial[] +== 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. + +[source, AsciiDoc] +---- +:technical-committee-number: 2 +:technical-committee: Fasteners +:subcommittee-number: 11 +:subcommittee: Fasteners with metric external thread + +This document was prepared by Technical Committee ISO/TC {technical-committee-number}, _{technical-committee}_, Subcommittee SC {subcommittee-number}, _{subcommittee}_. +---- + +== 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, AsciiDoc] +---- +[[figureC-1]] +.Typical gelatinization curve +image::images/rice_image2.png[Image of the gelatinization curve] +---- ++ +.Rendered image caption +image::/assets/author/tutorials/references_img_anchor.jpg[] + +. To reference an anchor, type the anchor name like this `\<>`. ++ +[source, AsciiDoc] +---- + <> gives an example of a typical gelatinization curve. +---- ++ +.Rendered reference +image::/assets/author/tutorials/references_img_target.jpg[] + +. To set an alternative text other than the anchor text, append the text inside the brackets using a comma. ++ +[source, AsciiDoc] +---- +<> gives an example of a typical gelatinization curve. +---- + +// 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. + +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: + +* 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.adoc[Deep-dive into cross-references]. +end::tutorial[] + diff --git a/author/topics/inline_markup/text_formatting.adoc b/author/topics/inline_markup/text_formatting.adoc new file mode 100644 index 00000000..72a1f963 --- /dev/null +++ b/author/topics/inline_markup/text_formatting.adoc @@ -0,0 +1,341 @@ +--- +layout: author-docs +title: Text formatting +--- += Text formatting +tag::tutorial[] +tag::text-markup[] + +Metanorma supports extensive inline formatting functionality. +The following formatting macros are available in Metanorma. + +== Basic markup + +AsciiDoc allows you to: + +* Emphasize words in *bold* using asterisks +* _Italicise_ words with underscores +* Apply `monospace` format using backticks +* Specify superscript and subscript characters (CO~2~, x^4^) + +.Example of basic inline markup +==== +[source,adoc] +---- +*bold* +_italic_ +`monospace` +^superscript^ +~subscript~ +---- + +Renders as: + +*bold* +_italic_ +`monospace` +^superscript^ +~subscript~ +==== + +end::text-markup[] + +=== Strikethrough + +The `strike` command renders text with a middle line strikethrough. + +The syntax is as follows: + +[source,asciidoc] +---- +[strike]#text# +---- + +Where: + +* `text` is the text to be rendered with the strikethrough style + +[example] +.Illustration of strikethrough text in Metanorma. +==== +[source,asciidoc] +---- +[strike]#strike through text# +---- + +renders: + +image::/assets/author/topics/inline_formatting/fig-strikethrough.png[Illustration of strikethrough text] +==== + + +=== Small caps + +The `smallcap` command renders text in small capital letters. + +The syntax is as follows: + +[source,asciidoc] +---- +[smallcap]#text# +---- + +Where: + +* `text` is the text to be rendered in small caps + +[example] +.Illustration of small caps text +==== +[source,asciidoc] +---- +[smallcap]#small caps text# +---- + +renders: + +image::/assets/author/topics/inline_formatting/fig-smallcaps.png[Illustration of small caps text in Metanorma] +==== + +=== Underline + +The underline command renders text with an underline. [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.2]. + +The syntax is as follows: + +[source,asciidoc] +---- +[underline]#text# +---- + +Where: + +* `text` is the text to be underlined + +[example] +.Illustration of underlined text +==== +[source,asciidoc] +---- +[underline]#underline text# +---- + +renders: + +image::/assets/author/topics/inline_formatting/fig-underline.png[Illustration of underlined text in Metanorma] +==== + + + +=== Numeric ranges + +Numeric ranges, like dates (e.g., _1981–1995_), make use of +_en dashes_ in between the numbers, usually without any white space around. + +At the time writing, there is no AsciiDoc encoding to render en dashes. + +In Metanorma, there is a vision of implementing a semantic encoding for +numeric ranges, perhaps an option like `range:[n,m]` or shorthands like `n..m`. + +For the time being, the existent workaround for such cases is +the use of entity codes, more specifically: + +[source,adoc] +---- +&‌ndash; +---- + +[example] +.Examples of encoding numeric ranges +==== +[source,asciidoc] +---- +See chapters 15–17... + +Issues 18–20 are in fact a single issue... + +_Laser Physics_ *17* 1017–1024 (2007). +---- + +renders: + +____ +See chapters 15–17... + +Issues 18–20 are in fact a single issue... + +_Laser Physics_ *17* 1017–1024 (2007). +____ +==== + + +=== Character substitutions + +tag::char-subs[] + +Metanorma AsciiDoc supports +https://docs.asciidoctor.org/asciidoc/latest/subs/replacements/[Asciidoctor-style character substitutions] +as shown in <>. + +Metanorma AsciiDoc also recognises HTML and XML character references, +and decimal and hexadecimal Unicode code points. + +[[table-char-sub]] +.Supported Metanorma AsciiDoc character substitutions +[cols="a,2a,a"] +|=== +|Source |Rendered as | Note + +|pass:[(C)] | (C) (Unicode 'Copyright Sign' `U+00A9`)| +|pass:[(R)] | (R) (Unicode 'Registered Sign' `U+00AE`)| +|pass:[(TM)] | (TM) (Unicode 'Trade Mark Sign' `U+2122`)| +|`-` | — (Unicode 'Em Dash' `U+2014`) | See NOTE below. +|pass:[...] | ... (Unicode 'Horizontal Ellipsis' `U+2026`)| +|pass:[->] | -> (Unicode 'Rightwards Arrow' `U+2192`)| +|pass:[=>] | => (Unicode 'Rightwards Double Arrow' `U+21D2`)| +|pass:[<-] | <- (Unicode 'Leftwards Arrow' `U+2190`)| +|pass:[<=] | <= (Unicode 'Leftwards Double Arrow' `U+21D0`)| +|`'` | Smart single quote, smart apostrophe | +|`"` | Smart double quote | + +|=== + +NOTE: Replacement of `-` only occurs when placed between two word +characters, between a word character and a line boundary, or flanked +by spaces. Flanking spaces (as in `x -- y`) are rendered as thin +spaces (Unicode 'Thin Space' `U+2009`). + +// `--` is rendered as an en-dash (–), which is not catered for by escapes. + +end::char-subs[] + +end::tutorial[] + + +=== CSS declarations + +The `css` command is used to wrap content with a CSS declaration +(https://developer.mozilla.org/en-US/docs/Web/API/CSS_Object_Model/CSS_Declaration[MDN]) +[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6]. + +This feature only applies to HTML output. + +NOTE: CSS declarations are also used within the HTML `style` attribute. + +The syntax is as follows: + +[source,asciidoc] +-- +[css {css-directive}]#{styled-text}# +-- + +Where: + +* `{css-directive}` is a CSS declaration + +* `{styled-text}` is text where the CSS declaration is to be applied + +[example] +.Example of applying a custom CSS declaration to content +==== +[source,asciidoc] +-- +[css font-family:"Noto Sans JP"]#お好み焼き# + +[css font-family:"Noto Sans Canadian Aboriginal"]#ᓀᐦᐃᔭᐍᐏᐣ# +-- +==== + + +=== Identifier + +The `identifier` command, used to indicate that its contents are an identifier +as semantic markup (and not to be processed as a +hyperlink) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.2]. + +The syntax is as follows: + +[source,asciidoc] +---- +identifier:[my-identifier] +---- + +Where: + +* `my-identifier` is the identifier to be encoded. + + +This functionality is very useful for encoding URIs, which can be virtually +indistinguishable from URLs that can be resolved. URIs very often cannot +be resolved since they are simply namespaced identifiers. + +[example] +.Example of rendering a URI using the `identifier` command +==== +[source,asciidoc] +-- +identifier:[https://schemas.isotc211.org/19115/-1/mdb/1.3] +-- + +renders: + +____ +`https‌://schemas.isotc211.org/19115/-1/mdb/1.3` +____ +==== + +[example] +.Example of rendering a URN using the `identifier` command +==== +[source,asciidoc] +---- +identifier:[urn:iso:std:iso:8601:-1:en] +---- + +renders: + +____ +`urn:iso:std:iso:8601:-1:en` +____ +==== + + +=== Semantic spans + +The `span` command is used to introduce semantic markup into +Metanorma text [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.1.6]. + +The syntax is as follows: + +[source,asciidoc] +---- +span:category[text] +---- + +Where: + +* `category` is a semantic label for the content given as `text` +* `text` is the textual content + +Here, the _text_ is tagged as belonging to _category_. + +A semantically-tagged text with `span` is not normally rendered any different to +normal, although the semantic markup introduced can be used to influence +rendering. + +NOTE: Only certain Metanorma flavors support enhanced rendering for +semantically-tagged content. + + +=== Nesting of styles + +Character styles can be nested within each other, with both constrained and +unconstrained formatting marks. + +[source,asciidoc] +-- +*Boldmono__space__* +-- + +NOTE: See https://docs.asciidoctor.org/asciidoc/latest/text/[Asciidoctor Text]. + diff --git a/author/topics/metadata.adoc b/author/topics/metadata.adoc new file mode 100644 index 00000000..c9cd1bbd --- /dev/null +++ b/author/topics/metadata.adoc @@ -0,0 +1,152 @@ +--- +layout: author-docs +--- +== Metadata and document attributes + +=== General + +tag::tutorial[] +tag::metadata-intro[] + +Information about a document itself is called the "metadata" of the document. +The document header is where metadata is entered. +Metadata is specified by using document attributes. + +Document attributes are used in the following ways: + +* provide semantic information for the document +* modify visual appearance of output format +* adjust the document generation process + +You can specify metadata about: + +* Authors: Issuing organization, authors, and their location +* Document information: Title, language, document stages (draft, published, etc.) copyright holder, etc. +* Identifiers: Document numbers, ISBNs, URIs +* Dates: Draft dates, revision dates, publishing date, copyright year, etc. + +Some metadata influence how the document is generated and should only be +used by advanced users. Often, they will require familiarity with the +structures and processes of the flavor's organization. + +NOTE: Some of the metadata is visible in the document, such as `:title:`, while +others are not visible but still affect how your document is generated. + + +A document attribute looks like this: + +[source,adoc] +---- +:title: My document +:draft: +---- + +Document attributes are used as simple flags like on/off switches, which do +not take a value, while others accept one or more values. + +NOTE: The order of document attributes generally does not matter to Metanorma, +except that a document attribute with the same key can be overwritten by a +subsequent definition of the same attribute below the original definition. + +end::metadata-intro[] + + +This is an example for an ISO deliverable: + +[source,adoc] +---- += Rice model <1> +:docnumber: 17301 <2> +:doctype: international-standard <3> +:copyright-year: 2021 +:language: en +:mn-document-class: iso <4> +:technical-committee: Food products <5> +:draft: <6> +:mn-output-extensions: xml,html,doc,html_alt <7> +---- + +<1> Document title +<2> `:docnumber:` is the first document attribute, and it has the value _17301_ +<3> `:doctype:` defines the type of document, for example `international-standard`, `technical-report`, `guide`, etc. The allowed values for this attribute are specific to each flavor. +<4> `:mn-document-class:` indicates the Metanorma flavor the document should be checked against. +<5> The committee responsible for the document. +<6> `:draft:` renders comments as well. The attribute does not take any values: it is either present or not. +<7> `mn-output-extensions` specifies the generated output formats. It can take several comma-delimited values. + +end::tutorial[] + + +// :fullname: Your Name <6> +// :fullname_2: Co-Authors Name +// :address: Chemin de Blandonnet 8 + \ <7> +// CP 401 - 1214 Vernier + \ +// Geneva + \ +// Switzerland + +// <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:`. + + +== Which attributes to specify? + +The attributes required or allowed to be specified for given document +depend on the type of document and the Metanorma flavor used. + +See link:/author/ref/document-attributes/[generic attribute reference] +for attributes supported by most Metanorma flavors. + +When using one of the officially supported Metanorma flavors, +please consult your flavor's author documentation. + + +=== Re-using attributes in text + +The body of the document can reference the values of document attributes. +Here's an example of referencing committee-related metadata entries: + +[source,adoc] +---- +:technical-committee-number: 184 +:technical-committee: Automation systems and integration +:subcommittee-number: 4 +:subcommittee: Industrial data +... + +This document was prepared by Technical Committee ISO/TC +{technical-committee-number}, _{technical-committee}_, Subcommittee SC +{subcommittee-number}, _{subcommittee}_. +---- + +If the corresponding document attributes are not populated in the header, then +the references themselves will not be populated. + + +=== Dealing with Unicode characters + +Document attribute values that contain Unicode characters must be entered +directly as Unicode. + +Any non-ASCII characters in document attribute values, or dashes for compound +titles, will need to be entered as Unicode. + +If you need to have non-ASCII characters in document title, or dashes for +compound titles, you will need to enter them directly as Unicode. Document +attribute values, unlike document text, cannot deal with +https://www.w3schools.com/html/html_entities.asp[HTML entities]. + +As an example, this would work: + +[source,adoc] +-- +:title-part-en: Information Technology—Security +:title-main-fr: Spécification et méthodes d'essai +-- + +Entering them as HTML Entities or XML Entities would not: + +[source,adoc] +-- +:title-part-en: Information Technology\—Security +:title-main-fr: Sp\écification et m\éthodes d'essai +-- diff --git a/author/topics/building.adoc b/author/topics/output.adoc similarity index 96% rename from author/topics/building.adoc rename to author/topics/output.adoc index 9c5ce4b6..f8d25a8a 100644 --- a/author/topics/building.adoc +++ b/author/topics/output.adoc @@ -1,9 +1,8 @@ --- layout: author-docs +title: Generating output --- -= Building documents - To build a Metanorma document, you need to use command-line Metanorma tool. Depending on how you link:../install/[got Metanorma installed], the tool would either be available on your machine directly, or through a Docker container. diff --git a/author/topics/building/font-management.adoc b/author/topics/output/font-management.adoc similarity index 100% rename from author/topics/building/font-management.adoc rename to author/topics/output/font-management.adoc diff --git a/author/topics/building/output-formats.adoc b/author/topics/output/output-formats.adoc similarity index 100% rename from author/topics/building/output-formats.adoc rename to author/topics/output/output-formats.adoc diff --git a/author/topics/building/validation.adoc b/author/topics/output/validation.adoc similarity index 100% rename from author/topics/building/validation.adoc rename to author/topics/output/validation.adoc diff --git a/author/topics/reviewing.adoc b/author/topics/reviewing.adoc new file mode 100644 index 00000000..f780ac3a --- /dev/null +++ b/author/topics/reviewing.adoc @@ -0,0 +1,59 @@ +--- +layout: author-docs +title: Reviewing documents +--- + +You can annotate a Metanorma AsciiDoc document with comments and `TODO`s to indicate a pending action. + +[NOTE] +==== +Reviewer notes are only rendered +if `link:/author/ref/document-attributes/#draft[:draft:]` attribute has been specified +for the document(s). +==== + +== Reviewer comments +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). +. 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 `\****`. +. Enter your comment. +. Close the comment block with four asterisks `\****`. + +.Example of a comment +[source,asciidoc] +-- +=== Address Profile Definition (AddressProfileDescription) + +This is a clause address [[A]]proflie[[B]] definition + +[reviewer="Nick Nicholas",date=20180125T0121,from=A,to=B] +**** +proflie?! +**** +-- + +which renders + +.Illustration of a reviewer comment covering a span of text. (the `:draft:` attribute needs to be set in the document in order to render any reviewer notes.) +// TODO: image not found +// image::/assets/author/topics/document-format/reviewer-notes/fig-reviewer-note-example.png[Illustration of a reviewer comment covering a span of text] + +== TODO expressions + +Metanorma treats `TODO` as an admonition label, and converts it into a reviewer note. +The `from`, `to` `reviewer` and `date` attributes are all treated as optional. + +.Example of a TODO +[source,asciidoc] +---- +TODO: This is treated as a reviewer note. + +[TODO] +==== +This is also treated as a reviewer note +==== +---- \ No newline at end of file diff --git a/author/topics/sections.adoc b/author/topics/sections.adoc new file mode 100644 index 00000000..6eabad63 --- /dev/null +++ b/author/topics/sections.adoc @@ -0,0 +1,361 @@ +--- +layout: author-docs +title: Document sections +--- + += Document sections + +== General + +tag::tutorial[] + +Sections define hierarchy levels in a document, as chapters do. +In AsciiDoc, sections are encoded with titles prefixed by equal signs (`=`). + +* The document title is considered the highest section in the hierarchy, and is +created by prepending a `=` sign in front of the heading. +* Subsequent sections are encoded with titles prefixed with least two equal signs: +** `==` indicates a first-level section; +** `===` indicates a second-level section; +** `====` indicates a third-level subsection; +** and so on. + + +[example] +.Example of setting document and section titles +==== +[source,adoc] +---- += Document title + +== Section 1 + +=== Section 1.1 + +==== Section 1.1.1 + +===== Section 1.1.1.1 + +== Section 2 + +=== Section 2.1 + +... +---- +==== + + +== Section titles + +=== Pre-defined section titles + +Sections in a document are composed and placed in their appropriate places +inside the Metanorma document model. + +Metanorma utilizes the following pre-defined section titles to identify specific +kinds of sections in the document: + +* `Abstract` +* `Foreword` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] +* `Introduction` +* `Acknowledgements` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] +* `Scope` +* `Normative references` +* `Terms and definitions` +* `Symbols and abbreviated terms` +* `Symbols` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] +* `Abbreviated terms` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] +* `Bibliography` +* `Misc-Container` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7] + +// 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. + +The content body, or annexes, are entered as normal sections without need for +pre-defined titles. + +Fixed section names are specific to either the preface of a document, or the main body; +so for example an instance of "Introduction" the main body of the text will not be treated +as part of the preface. + +NOTE: The underlying document model behind all Metanorma flavors is called the +StandardDocument model, also abbreviated as "StanDoc". +The available section types available in StanDoc are reproduced in this section. +StanDoc represents the harmonized common requirements of standardization +documents, not the document model of a particular SDO. + +.UML representation of section classes in Metanorma StanDoc +image::https://raw.githubusercontent.com/metanorma/metanorma-model-standoc/main/images/StandardDoc_Sections.png[UML representation of section classes in Metanorma StanDoc] + + +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. + +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 + +Entering titles that deviate from the pre-defined titles, or in languages other than English requires +explicit declaration of those section types. + +The section type is declared between square brackets `[ ... ]` immediately +above the section title. + +For these types of sections, enter them without + +* Abstract: `[abstract]` +* Foreword: `[heading=foreword]` +* Preface sections: `[preface]` +* Introduction: `[heading=introduction]` +* Acknowledgements: `[acknowledgments]` +* Scope: `[heading=scope]` +* Bibliography, Normative references: `[bibliography]` +* Terms and definitions: `[heading=terms and definitions]` +* Symbols and abbreviated terms: `[heading=symbols and abbreviated terms]` +* Index: `[index]` +* Annexes: `[appendix]` + +NOTE: Documents can contain only one Abstract, one Acknowledgements section, and one Index. + +The following example indicates usage of the section titles. + +[source,adoc] +---- += Document title + +== Abstract + +== Foreword + +[preface] <1> +== Introduction to version 3 of this standard + +[bibliography] <2> +== Normative references + +[heading=terms and definitions] <3> +== Terms, definitions, and abbreviations + +[bibliography] +== Bibliography +... + +[appendix,obligation=informative] <4> +== Additional content +... +---- + +<1> This section is meant to be the introduction but the title deviates from the +pre-defined title. The `[preface]` declares it as such. +<2> "Normative references" is encoded with the `[bibliography]` declaration. +<3> The "heading" declaration assigns the section as a particular kind. +<4> "Additional content" is an annex and needs to be declared explicitly. +Normative status of the annex is defined by adding the `obligation` option. + +end::tutorial[] + +[NOTE] +==== +The above section titles as detected by Metanorma are case-insensitive. +While ISO Directives Part 2 demands clause titles to be in +https://en.wikipedia.org/wiki/Letter_case#Sentence_case[sentence case], +some organizations utilize +https://en.wikipedia.org/wiki/Letter_case#Title_case[title case]. +==== + +[NOTE] +==== +A dedicated topic link:../section-terms/[expands on "`Terms and definitions`" section grammar]. +==== + + +=== Blank subclause headings + +Blank subclause headings can be given like this: + +[source,asciidoc] +-- +=== {blank} +-- + +These are used when you want to give a subclause number for a new subclause, +but without an associated header text. For example, + +[source,asciidoc] +-- +=== Physical and chemical characteristics + +==== {blank} + +The mass fraction of moisture, determined in accordance with... +-- + +renders as + +____ +*4.2. Physical and chemical characteristics* + +*4.2.1.* The mass fraction of moisture, determined in accordance with... +____ + +[NOTE] +==== +This notation should not be used to implement paragraph numbering as required for e.g. metanorma-un. +The link:/flavors/un/[UN Metanorma flavor] treats each paragraph +as a distinct clause and automatically numbers it. +==== + +=== Inline headings + +Inline subclause headings (e.g. for test methods) are indicated by preceding the heading +with the `[%inline-header]` option attribute. So in the Rice Model document, + +[source,asciidoc] +-- +[%inline-header] +==== Sieve, + +with round perforations of diameter 1,4 mm. +-- + +renders as + +____ +*A.2.1.1. Sieve,* with round perforations of diameter 1,4 mm. +____ + +=== Variant titles + +Variant titles [added in +https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5] are entered +as paragraphs with a `variant-title` role attribute within a clause, as follows: + +[source,adoc] +---- +=== Proper title + +[.variant-title,type=sub] +This is the variant title + +Text of section. +---- + +Variant titles of type `sub` are rendered as subtitles of clauses. + +=== Floating titles + +WARNING: Intended for legacy support only. Use with care. + +A "`floating title`" is a title that is placed outside the numbered hierarchy of +clauses. This means that a floating title is not uniquely referable like normal +clauses. + +Since the hierarchical structure of standards documents is critical to their +proper referencing, floating titles are commonly disallowed by standards +documents. Nonetheless, for legacy support reasons, floating titles are +supported in Metanoma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.11.4]: + +[source,adoc] +---- +=== Section 2.1 + +[discrete] +==== I am a floating title within section 2.1 + +==== Section 2.1.1 +---- + +NOTE: Floating titles are sometimes referred in AsciiDoc as "`discrete titles`". + + + +== Sections deeper than 5 levels + +Standards can contain many levels of embedding: ISO/IEC DIR 2 only considers +it a problem if there are more than 7 levels of embedding. + +To realise higher levels of embedding, +prefix a 5-level section title with the attribute `level=`: + +NOTE: Asciidoctor AsciiDoc permits only five levels of section embedding +(not counting the document title). + + +[source,asciidoc] +-- +// Six equal signs for five levels +====== Clause 5A + +[level=6] +====== Clause 6A + +[level=7] +====== Clause 7A + +[level=7] +====== Clause 7B + +[level=6] +====== Clause 6B + +====== Clause 5B +-- + +This generates the following ISO XML: + +[source,xml] +-- + + + Clause 5 + + + + Clause 6 + + + + Clause 7A + + + + + Clause 7B + + + + + + Clause 6B + + + + + + Clause 5B + + +-- + +and the rendering would be something like + +*1.1.1.1.1 Clause 5A* + +*1.1.1.1.1.1 Clause 6A* + +1.1.1.1.1.1.1 Clause 7A + +1.1.1.1.1.1.2 Clause 7B + +*1.1.1.1.1.2 Clause 6B* + +*1.1.1.1.2 Clause 5B* + diff --git a/author/topics/sections/annexes.adoc b/author/topics/sections/annexes.adoc new file mode 100644 index 00000000..b5765a31 --- /dev/null +++ b/author/topics/sections/annexes.adoc @@ -0,0 +1,82 @@ +--- +layout: author-docs +title: Annexes +--- +== Annexes + +=== General + +All annexes must be preceded by the style attribute `[appendix]`, or +([added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.27]) +the role attribute `[.appendix]`. The latter can be used to combine the appendix. +with another style attribute, such as `[bibliography]`, though this is not recommended +practice. + +Like all clauses, annexes are **normative by default**, +an informative annex is indicated with `[appendix,obligation=informative]`. + +The **numbering** of annexes and appendices is automatic: +do not insert "Annex A" or "Appendix 1" as part of the title. + +Annex and Appendix **titles** can be left blank, as with Clauses. + +=== Term Annexes, Symbols Annexes, Bibliography Annexes + +Normally in Metanorma, the sections describing terms and definitions, symbols +and abbreviated terms, and bibliographic references are contained in a main +clause. + +However, it is possible for such clauses to be contained in annexes instead. In +fact, this is done by default for the "Terms and References" section in the NIST +flavour of Metanorma. + +In rendering, these annexes are treated identically as when those sections were +in the main body. + +However, the Metanorma information model does not permit a clause to be an annex +and a terms or a bibliographic clause at the same time. + +Such clauses are modelled as an annex *containing* a terms clause or bibliographic clause: + +[source,asciidoc] +---- +[annex] +== Bibliography + +[bibliography] +=== Bibliography +---- + +In order to render such annexes as expected, the following rules are +applied [added in https://github.com/metanorma/isodoc/releases/tag/v2.0.9]: + +* If an annex contains multiple subclauses, it is rendered as usual. +* If an annex contains a single subclause, and that subclause is a Terms & Definitions, +Symbols & Abbreviated Terms, or Bibliographic section, +** The title for that subclause is skipped in rendering +** The subclause itself is skipped for the purposes of numbering; if it has any sub-subclauses +of its own, they are numbered as immediate child clauses of the annex. + +So: + +[source,asciidoc] +---- +[annex] +== Terminology + +=== Terms and definitions + +==== First Term + +==== Second Term +---- + +is rendered like + +____ +*Annex A. Terminology* + +*A.1 First Term* + +*A.2 Second Term* +____ diff --git a/author/topics/document-format/bibliography.adoc b/author/topics/sections/bibliography.adoc similarity index 78% rename from author/topics/document-format/bibliography.adoc rename to author/topics/sections/bibliography.adoc index 631cb979..a5928fe0 100644 --- a/author/topics/document-format/bibliography.adoc +++ b/author/topics/sections/bibliography.adoc @@ -9,6 +9,12 @@ layout: author-docs In standard documents typically there are two types of references, namely the "`normative references`" and the "`bibliography`" (informative references). +The following fixed clause names identifies a bibliography: + +* `Normative references` +* `Bibliography` + + Every bibliographic section must be preceded by the style attribute `[bibliography]` so that references they contain may be recognized as such: @@ -122,7 +128,7 @@ and "`Informative references`" are separate, where the -- -See https://www.metanorma.org/author/ietf/topics/references/[References (AsciiRFC v3)] +See link:/author/ietf/topics/references/[References (AsciiRFC v3)] for further details. ==== @@ -149,13 +155,14 @@ Any initial text in a Normative Reference section (before the first reference) is replaced by predefined text specific to the Metanorma flavour. In order to override this, initial text can be provided by the user -as a note of type "`boilerplate`" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.2]: +as a open block with "`boilerplate`" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.0] +(formerly: a note of type "`boilerplate`" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.9.2]) [source,asciidoc] ---- == Normative references -[NOTE,type=boilerplate] +[.boilerplate] -- The following contract document is referred to in the text in such a way that some or all of its content constitutes requirements of this @@ -488,6 +495,83 @@ ISO 20483:2013. _Cereals and cereal products -- Determination of moisture conten ____ ==== +One of the online bibliographic databases Metanorma allows access to is the CrossRef registry +of DOI identifiers [added in https://github.com/relaton/relaton-cli/releases/tag/v1.14.0]. That means that +any book, journal article, conference paper or dataset that has been identified with a DOI identifier +can be cited by providing its DOI identifier as its bibliographic tag. Metanorma will import the bibliographic +details of the reference from CrossRef, and format them in the required format of the current Metanorma flavour. + +[example] +.Example of specifying an auto-fetched DOI reference +==== +The following will trigger auto-fetching: + +[source,asciidoc] +-- +* [[[ref1,doi:10.1045/november2010-massart]]] +-- + +and gets rendered as: + +____ +Massart D., Shulman E., Nicholas N., Ward N., & Bergeron F. Taming the Metadata Beast: ILOX. _D-Lib Magazine_ Vol. 16 No. 11/12. November 2010. Available from: http://dx.doi.org/10.1045/november2010-massart +____ +==== + +This functionality has also been extended to the OpenLibrary registry of +ISBN identifiers [added in https://github.com/relaton/relaton-cli/releases/tag/v1.17.2]. +This is triggered by an identifier string prefixed with "ISBN ". + +[example] +.Example of specifying an auto-fetched ISBN reference +==== +The following will trigger auto-fetching: + +[source,asciidoc] +-- +* [[[ref1,ISBN 978-0-12-064481-0]]] +-- + +and gets rendered as: + +____ +Arvo, J. _Graphics gems II_. 1991. Boston, London: AP Professional. +____ +==== + + +=== Automatic fetching of joint publications + +Metanorma recognises two types of joint publication: + +* Joint publications proper (or Merged publications), +in which the one document is considered to be published simultaneously +by two different standards bodies. In the case of ISO and IEC, there are longstanding partnerships with +each other and with IEC, and this is reflected in the identifier assigned by the standards organisation +(e.g. ISO/IEC DIR 1). In other cases, the document is assigned a different identifier by each of +the standards organisations involved, but it is still considered to be the same publication, and is +described in a single bibliographic entry. +* Dual publications, for which the publications are treated as separate bibliographic entries, listed +together with phrasing like "also published as:". In dual publications, the publications are regarded +as separate activities with separate metadata, rather than a joint coordinated responsibility. + +In case the partnership is not acknowledged in the document identifier (the documents are assigned +two separate identifiers), the two separate bibliographic entries can still be fetched by Relaton, +and brought together in the Metanorma bibliography [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.1]. + +* `[[[anchor,merge(CODE1, CODE2)]]]` merges together the two bibliographic entries fetched under +CODE1 and CODE2: the bibliographic entry is that of CODE1, but the publication information of CODE2 +(the publishing organisation and the distinct document identifier) are added to the entry. For example, ++ +==== +ISO 10712 | ITU-R 232. _ISO title of document_. International Organization for Standardization and International Telecommunications Union. +==== + +* `[[[anchor,dual(CODE1, CODE2)]]]` treats the two bibliographic entries separately. For example, ++ +==== +ISO 10712. _ISO title of document_. International Organization for Standardization. Also published as: ITU-R 232. _ITU title of document_. International Telecommunications Union. +==== [[other-databases]] === Referencing from a Metanorma collection @@ -602,14 +686,21 @@ The span categories supported are: * `surname`: Author surname. * `initials`: Author initials. * `givenname`: Author given name. +* `fullname`: Combination of author surname and initials or given names, according to strcit syntax +(see below) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.0] * `organization`: Corporate author. * `surname.XXX`: Contributor surname, with role _XXX_ (e.g. _editor_). * `initials.XXX`: Contributor initials, with role _XXX_ (e.g. _editor_). * `givenname.XXX`: Contributor given name, with role _XXX_ (e.g. _editor_). +* `fullname.XXX`: Contributor full name, with role _XXX_ (e.g. _editor_). * `organization.XXX`: Corporate contributor, with role _XXX_ (e.g. _editor_). * `title`: Title. * `in_title`: Title of containing bibiographic item (for types `inbook, inproceedings, incollection`, the title of the book, proceedings, collection containing the item). +* `in_surname`, `in_initials`, `in_givenname`, `in_organization`: Name of contributor for containing +bibliographic item (for types `inbook, inproceedings, incollection`, the author or more usually editor +of the book, proceedings, collection containing the item. So `in_surname.editor`, `in_givenname.editor` +give the name of the editor of the book or proceedings that a paper is included in). * `series`: Series title. (For articles, this is the journal title.) * `docid`: Document identifier. * `docid.XXX`: Document identifier, of type _XXX_. @@ -617,12 +708,34 @@ the title of the book, proceedings, collection containing the item). * `pubplace`: Place of publication. * `date`: Date published. * `date.XXX`: Date with type _XXX_ (e.g. _published_, _created_, _issued_) +* `edition`: Edition +* `version`: Version +* `note`: Note (can also be used for miscellaneous content) * `uri`: URI. * `uri.XXX`: URI, of type _XXX_. * `pages`: page or page range (e.g. _9_, _9-11_) * `issue`: issue or issue range (e.g. _9_, _9-11_) * `volume`: volume or volume range (e.g. _9_, _9-11_) * `type`: Document type (e.g. _standard_, _book_, _inbook_): suppressed from rendering. +The list of valid document types is given in https://www.relaton.org/specs/model/bibtype/[Relaton model -- Bibitem type]. + +NOTE: The surname must always precede the initials or given name for a given author in spans, +to prevent ambiguity and confusion in parsing the citation. +The rendered ordering of initials/given name and surname for the first +and for subsequent names is determined by the flavour citation stylesheet. +So `span:surname[Fields], span:initials:[W.C.]`, never `span:initials:[W.C.] span:surname[Fields]`. + +NOTE: After the first instances of `surname` and either `initials` or `givenname`, any +subsequent instances of `surname` or either `initials` or `givenname` are +interpreted as belonging to a new contributor of the same role. + +NOTE: `span:fullname[]` is intended as a convenience method to substitute `span:surname[]`, +`span:initials[]`, `span:givenname[]` in a single macro. It has a strict syntax, and any +special cases need to be marked up with the separate, explicit name parts instead: + +* The surname is a single word (space-delimited), occuring at the end. So in `span:fullname[A. D. Navarro Cortez]`, only _Cortez_ is a surname: to make _Navarro Cortez_ a surname, you will need to mark it up as `span:initials[A. D.] span:surname[Navarro Cortez]`. But in `span:fullname[A. D. Navarro-Cortez]`, the surname is _Navarro-Cortez_. +* Anything before the surname is a given name. So in `span:fullnamename[J. Edgar Hoover]`, both _J._ and _Edgar_ are processed as given names. +* If everything before the surname ends in a full stop, they are all deemed initials. So in `span:fullname[A. D. Navarro Cortez]`, _A. D._ are parsed as initials. [example] .Example encoding of a bibliographic item inline with semantic markup @@ -630,7 +743,8 @@ the title of the book, proceedings, collection containing the item). [source,asciidoc] ---- * [[[A, B]]], - span:surname[Wozniak], span:initials[S.] & span:givenname[Steve] span:surname[Jobs]. + span:surname[Wozniak], span:initials[S.], span:surname[Jobs], span:givenname[Steve], + & surname:[Hoover], span:initials[J.] span:givenname[Edgar]. span:date.issued[1991]. span:date[1996]. span:title[_Work_]. @@ -648,9 +762,17 @@ the title of the book, proceedings, collection containing the item). ---- ==== +Note the distinction in the example between Wozniak and Jobs (authors of the paper), +and Gates and UNICEF (editors of the book including the paper). Similarly, note the +distinction between the title of the paper (_Work_), and the title of the book including +the paper (_Collected Essays_). + After the first instances of `surname` and either `initials` or `givenname`, any -subsequent instances of `surname` or either `initials` or `givenname` are +subsequent instance of `surname` is interpreted as belonging to a new contributor of the same role. +Any given names and surnames MUST follow the surname that they relate to. If the names +are ordered differently between the first and subsequent name, e.g. _Wozniak, S. & Steve Jobs_, +that will be taken care of in rendering: they cannot be annotated in that way. [NOTE] -- @@ -661,6 +783,18 @@ For presentations, * `organization.distributor` is the organizer of the conference -- +[IMPORTANT] +-- +The rendering of different bibliographic types is quite different in the various +stylesheets that SDOs follow, and strange things will happen if Metanorma gets the +bibliographic type wrong. Under Metanorma, the default bibliographic type is "standard", +and most SDOs render standards in bibliographies with very little data (no author, no +publisher, no date outside of the document identifier, and so on). + +If you use this notation to enter any document other than a standard, you *must* +specify the type of document, using `span:type[]`. +-- + [[asciibib]] === Entering with AsciiBib @@ -670,7 +804,7 @@ AsciiBib is a bibliography entry format that uses AsciiDoc definition lists to capture the structure of Relaton XML. This approach is documented in -https://www.relaton.org/specs/asciibib/[relaton.org]. +https://www.relaton.org/asciibib/[relaton.org]. [example] .Example of entering an entry using AsciiBib (ISO 123) with an AsciiBib ID @@ -756,7 +890,7 @@ Of course, any Relaton XML BibItem entries need to be valid, and using correct ==== -[[localities]] +[[citations_localities]] == Citations and localities === General @@ -782,7 +916,7 @@ cross-reference. A cross-reference `\<>` will be rendered as "`the foregoing reference`", and hyperlinked to the `ISO7301` reference. - +[[localities]] === Localities ==== General @@ -1002,6 +1136,12 @@ wording ("`and`"). ---- ==== +NOTE: If references are joined with semicolons and connectives, but the locality is not supplied +for a cross-reference, it is filled in by referring to the preceding conjoined +cross-reference [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.0]. +For example, `<>` is +corrected internally to the more explicit `<>`. + Trailing text after the sequence of `locality=reference` (or `locality{space}reference`) is treated as custom text for the cross-reference, as would occur normally in a typical cross-reference. @@ -1108,7 +1248,7 @@ The following input: ... -* [[[ISO7301,path(./iso7301.html,ISO 7301)]]] +* [[[ISO7301,path:(./iso7301.html,ISO 7301)]]] -- will render in HTML as: @@ -1147,6 +1287,30 @@ rendered [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v -- ==== +==== Styled cross-references + +As with link:/author/topics/document-format/xrefs#xref-styles[internal cross-references], cross-referenced +citations can have a `style` attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4]. +As of this writing, the only values allowed are the types of docidentifier value that can be substituted +for the primary identifier of the reference, for standards documents; those values will need to be looked up in +Relaton (and the Semantic XML of the document). For example, given the citation + +[source,xml] +---- + +... +ISO/FDIS 17664-1 +urn:iso:std:iso-fdis:17664:-1:ed-1:fr +... + +---- + +a crossreference `<>` will be populated by default with the primary or else the first +`docidentifier` value found, `ISO/FDIS 17664-1`. However, given `<>`, the +first `docidentifier` value of type `URN` will be sought instead, and the cross-reference +will be populated by default as `URN urn:iso:std:iso-fdis:17664:-1:ed-1:fr`. + + === Link-only references A standards document can be cross-referenced in Metanorma without that document @@ -1336,3 +1500,35 @@ The following encoding will hide the particular bibliographic reference. * [[[iso86011,hidden(ISO 8601-1:2019)]]] -- ==== + +=== CSV notation + +The notation shown up to this point for reference processing flags has the potential of being too complicated +to parse, if deeply nested or if the parentheses of flags are combined with the parentheses of user-supplied +labels or of "all parts". For that reason, an alternative notation is supported, involving key/value pairs +delimited by comma and equals signs in the anchor label [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.4]. +For example, the following two references are equivalent: + +[source,asciidoc] +---- +[bibliography] +== Normative references + +* [[[iso8601_1,nofetch((Date-Time)ISO 8601-1:2019)]]], _Date and time — Representations for information interchange — Part 1: Basic rules_ +* [[[iso8601_1a,nofetch=true,usrlabel=Date-Time,code=ISO 8601-1:2019]]], _Date and time — Representations for information interchange — Part 1: Basic rules_ +---- + +The CSV-based notation has the following keys: + +`nofetch`:: `true`|`false` +`hidden`:: `true`|`false` +`dropid`:: `true`|`false` +`local-file`:: (filename of local Relaton cache) +`repo`:: (repository name)/(document entry) +`path`:: (file path) +`number`:: (number, for a numeric ID of a citation) +`usrlabel`:: (user-supplied label of reference) +`code`:: (authoritative identifier of reference) + +If no key is supplied in the CSV entry, it is assumed to be a code; e.g. `nofetch=true,usrlabel=Date-Time,ISO 8601-1:2019` +is interpreted as `nofetch=true,usrlabel=Date-Time,code=ISO 8601-1:2019`. diff --git a/author/topics/document-format/section-terms.adoc b/author/topics/sections/concepts.adoc similarity index 93% rename from author/topics/document-format/section-terms.adoc rename to author/topics/sections/concepts.adoc index 27e6e888..a8278b54 100644 --- a/author/topics/document-format/section-terms.adoc +++ b/author/topics/sections/concepts.adoc @@ -1,7 +1,7 @@ --- layout: author-docs +title: Concepts, designations, terms and definitions --- - == Concepts, designations, terms and definitions === General @@ -131,6 +131,14 @@ foo: bar ____ ==== +Automated titles will only be generated if the terms & definitions clause +and its immediate children are exhaustively covered by the possibilities above: +each child element is either a definitions clause or a terms collection, or initial +boilerplate text, and there is only one of each type or combination of types. +If there are other clauses mixed in, or if there are multiple collections of terms, +Metanorma will not replace the terms, because its replacements will likely not be true; +for example, if there are two subclauses containing terms, no one subclause should be +named "Terms and definitions" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.6.2]. [[source]] ==== Concept source @@ -271,9 +279,11 @@ The predefined text at the start of the clause is adjusted to reflect both possibilities. In order to replace (override) the predefined text with custom -content, an initial subclause with the style attribute +content, an initial open block with the style attribute `[.boilerplate]` can be used to do -so [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0]. +so [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.0]. + +(Formerly, a clause with that style attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.7.0].) Input: @@ -281,25 +291,22 @@ Input: .Overridden predefined text ==== [source,asciidoc] --- +---- == Terms and definitions [.boilerplate] -=== My predefined text (<<<=== this will be stripped) - +-- This is predefined text that overwrites the default. * No, it does not follow ISO requirements * And no, it does not follow IEC requirements either +-- === Term 1 --- +---- Where: -* The title of the predefined text clause will be stripped (so you could equally - use `=== {blank}`); - * The custom predefined text is encoded as a subclause, so that its extent can be made unambiguous in initial processing. @@ -664,6 +671,9 @@ one or more processes creating or using product data ---- ==== +Duplicate designations under the same term of the same type are removed, with +a warning [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.8]; +e.g. the section heading "application" followed by `preferred:[application]`. ===== Admitted designations @@ -793,8 +803,9 @@ boolean (`true` or `false`) `absent`:: the designation is absent; value is boolean (`true` or `false`) -`letter-symbol`:: the designation is not a linguistic expression, but a letter or -symbol; value is boolean (`true` or `false`) +`letter-symbol`:: the designation is not a linguistic expression, but a letter, +symbol, formula, or equation; value is boolean (`true` or `false`), or else [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.7.2] +one of `letter`, `symbol`, `formula`, `equation`. Grammar of the designation is encoded as keys within the tag `grammar`: @@ -1056,6 +1067,8 @@ source. Metanorma allows the encoding of this more complex structure through embedding each distinct definition within an open block, with a `[.definition]` role attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6]. +Different definitions can be differentiated with different `type` +attributes [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.5.3] [example] .Multiple definitions for one designation @@ -1066,7 +1079,7 @@ attribute [added in https://github.com/metanorma/metanorma-standoc/releases/tag/ alt:[doohickey] -[.definition] +[.definition,type="official"] -- device performing an unspecified function @@ -1074,7 +1087,7 @@ device performing an unspecified function <> -- -[.definition] +[.definition,type="unofficial"] -- general metasyntactic variable @@ -1083,7 +1096,7 @@ general metasyntactic variable -- ---- -Multiple definitions are rendered in Metanorma as an ordered list of +Multiple definitions are rendered by default in Metanorma as an ordered list of definitions: .Rendering of multiple definitions for one designation @@ -1227,6 +1240,11 @@ This example adds the "IEV" termbase with a chosen anchor `ievtermbank`. -- ==== +Note that the clause should be in quotes, to indicate it is a single cross-reference; +a reference like `<>` would be interpreted as the clause +range 103 through 104. However, Metanorma will treat a reference with two hyphens +as a single cross-reference [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.2]. + Formally, in accordance with IEC/TC 1 advised practice, IEV references should be cited as `IEC 60050-nnn:yyyy`, where `n` is the top-level clause, and `yyyy` is the year when that particular specification was published. @@ -1242,7 +1260,7 @@ The following source: [source,adoc] ---- -<> +<> ---- will be rendered as: @@ -1292,6 +1310,28 @@ stem:[int_(t_2)^(t_1) bb(d) t] -- ==== +You may wish to go against IEC practice, and cite IEC 60050 as an entire document, +instead of converting references to individual parts of IEC 60050. +In that case, you need to use `IEC 60050 (all parts)` instead of `IEV` in your +bibliography. So a reference to + +[source,asciidoc] +---- +[.source] +<> + +... + +[bibliography] +== Bibliography + +* [[[ievtermbank,IEC 60050 (all parts)]]], _IEV: Electropedia_ +---- + +will have the bibliographic entry reference IEC 60050, instead of resolving that entry to +IEC 60050-103. + + ===== Citing terminological entries with numeric identifiers In ISO and IEC, terminological entries are technically identified by @@ -1429,16 +1469,12 @@ term:[rice] from which the husk only has been removed ==== Stem expressions -AsciiDoc does not permit macros to be nested inside other macros. - -Therefore the following markup which introduces a stem expression -as an admitted term, is considered illegal. +AsciiDoc permits macros to be nested inside other macros. -NOTE: The use of stem expressions as preferred terms is not a problem, -because the macro appears as a header. +Therefore the following markup shows that stem expressions can be used +as both admitted terms and preferred terms. [example] -.Bad `stem` example ==== [source,asciidoc] -- @@ -1449,27 +1485,6 @@ Time to launch. -- ==== -However, Metanorma will treat any standalone paragraph in a term section, -consisting of just a stem macro, as an admitted term: - -[example] -.Good `stem` example -==== -[source,asciidoc] --- -=== stem:[t_90] - -stem:[t_A] - -Time to launch. --- - -.Illustration of a term that uses stem expressions. -image::/assets/author/topics/document-format/section-terms/fig-term-stem.png[Illustration of a term that uses stem expressions] -==== - - - [[citeterms]] === Referencing concepts through mentions @@ -1519,6 +1534,11 @@ In this syntax, only the `term` argument is mandatory. * `term`: the concept designation being cited (mandatory). + +If a domain is used to disambiguate between two terms with the same designation, then +the domain must be prefixed to the term +in angle brackets [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.9]; +e.g. {{ whole rice}}. The domain may be dropped if the designation is unambiguous within the document. ++ The term must match the source term title for case, because case can be used to differentiate terms (e.g. _international standard_ and _International Standard_) [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.0.7]. @@ -2121,19 +2141,18 @@ The following rendering options, introduced with `options="..."`, are defined for concept mentions. `ital`:: italicise the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1] - -`ref`:: provide a reference for the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1] - `noital`:: do not italicise the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1] +`bold`:: boldface the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2] +`nobold`:: do not boldface the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.3.2] + +`ref`:: provide a reference for the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1] `noref`:: do not provide a reference for the rendered term [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.1] `linkmention`:: hyperlink the rendered term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6] - `nolinkmention`:: do not hyperlink the rendered term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6] `linkref`:: hyperlink the reference for the term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6] - `nolinkref`:: do not hyperlink the reference for the term to a term definition [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.6] If these options are missing, Metanorma applies the defaults for the current @@ -2141,25 +2160,27 @@ flavour. The default behaviour in Metanorma is: -* for all terms (italics and cited): `ital,ref,nolinkmention,linkref` +* for all terms (italics and cited): `ital,nobold,ref,nolinkmention,linkref` -* for acronyms (no special rendering): `noital,noref,nolinkmention,nolinkref` +* for acronyms (no special rendering): `noital,nobold,noref,nolinkmention,nolinkref` NOTE: In Metanorma for IEEE, the default behaviour is -`noital,noref,nolinkmention,nolinkref` for all terms (i.e. no special rendering +`noital,nobold,noref,nolinkmention,nolinkref` for all terms (i.e. no special rendering for a term cited within a term definition.) In ISO, the default behaviour for terms is refined: * for terms outside the "`Terms and definitions`" section: - `noital,noref,nolinkmention,nolinkref` (no special rendering); + `noital,nobold,noref,nolinkmention,nolinkref` (no special rendering); * for the first mention of a term within the "`Terms and definitions`" - section: `ital,ref,nolinkmention,linkref` (italics, cited, hyperlinked); + section: `ital,nobold,ref,nolinkmention,linkref` (italics, cited, hyperlinked); * for all subsequent mentions within the "`Terms and definitions`" section: - `ital,noref,nolinkmention,linkref` (italics, hyperlinked, no citation). + `ital,nobold,noref,nolinkmention,linkref` (italics, hyperlinked, no citation). + +In BSI, the default behaviour for terms is: `noital,bold,ref,nolinkmention,linkref` [example] .Using cited concepts with various options diff --git a/author/topics/sections/entering-bib.adoc b/author/topics/sections/entering-bib.adoc new file mode 100644 index 00000000..b63d5e19 --- /dev/null +++ b/author/topics/sections/entering-bib.adoc @@ -0,0 +1,60 @@ +--- +layout: author-docs +title: Entering a bibliographic entry +--- +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. + +== Entering a bibliographic entry + +To enter a reference entry: + +. Start a new unordered list (`*`) item. +. Enter triple square brackets (`[[[]]]`) which contain: ++ +* The anchor name used to reference this entry +* A document identifier + ++ +.Syntax for a bibliographic entry +[source, AsciiDoc] +---- +* [[[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. ++ +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: + +. Enter the anchor name like this: `\<>`. +. To specify a location within the cited document, you can add link:/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. + +.Example for a bibliography section +[source, AsciiDoc] +---- +[bibliography] +== Normative references + +* [[[ISO20483,ISO 20483:2013]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_ +* [[[ISO6540,ISO 6540:1980]]]. _Maize -- Determination of moisture content (on milled grains and on whole grains)_ +---- +Gets rendered as: + +* ISO 20483:2013. _Cereals and cereal products — Determination of moisture content — Reference method_ +* ISO 6540:1980. _Maize — Determination of moisture content (on milled grains and on whole grains)_ + +end::tutorial[] diff --git a/author/topics/sections/entering-terms.adoc b/author/topics/sections/entering-terms.adoc new file mode 100644 index 00000000..92190174 --- /dev/null +++ b/author/topics/sections/entering-terms.adoc @@ -0,0 +1,74 @@ +--- +layout: author-docs +title: Adding a term entry +--- +tag::tutorial[] + +Many standard documents contain a terminology section (or clause) that contains +definitions for terms used within the document. + +This section is typically called "`Terms and definitions`" and is recognized +by its section title. The designated name of this section differs per flavor, +so please check documentation of the particular flavor being used. + +== Creating a terms and definitions section + +It is important for a standards document to utilize terms unambiguously, +and therefore typically it will contain a definitive terms and +definition section. + +.Syntax for a "Terms and definitions" section +[source,adoc] +---- +== Terms and definitions +---- + +NOTE: The "Terms and definitions" section heading differs per SDO, please +refer to the appropriate documentation. + +== Entering a terminology entry + +To enter a terminology entry: + +. Start a new subsection under the "Terms and definitions" section. +. The term (the "designation") is entered as this section's heading. +. The definition is entered as this section's content. + +.Syntax for a simple terminology entry +[source,adoc] +---- +== Terms and definitions + +=== satellite + +artificial body placed in orbit around a planetary body +---- + +The terminology model in Metanorma is comprehensive as a superset of what is +defined in ISO 10241-1. Please refer to documentation for advanced features. + + +== Referencing a terminology entry + +A citation to a terminology entry is called a "concept mention". + +Concept mentions are entered using `{{..}}` double braces, where +the content of the double braces is the term (the "designation") itself. + +.Syntax for a concept mention +[source,adoc] +---- +== Terms and definitions + +=== satellite + +artificial body placed in orbit around a planetary body + +... + +== Another section + +The {{satellite}} has risen over the moon. +---- + +end::tutorial[] diff --git a/author/topics/sections/misc-container.adoc b/author/topics/sections/misc-container.adoc new file mode 100644 index 00000000..b92c6b2e --- /dev/null +++ b/author/topics/sections/misc-container.adoc @@ -0,0 +1,29 @@ +--- +layout: author-docs +title: Misc container +--- + +== Misc container + +=== General + +By default the single prefatory clause is identified with the pre-defined +section titles: + +* `Misc-Container` + +=== Misc-Container + +The `misc-container` element in Metanorma XML contains miscellaneous data +necessary for the processing of the document, that are not themselves part of +the document. + +Examples include the https://www.unitsml.org/[UnitsML] +definitions of units referenced in the document, or identifiers used as aliases of anchors in the document. + +If a preface clause is named `Misc-Container` (case-insensitive), its contents +are appended to the `misc-container` element for the document [added in +https://github.com/metanorma/metanorma-standoc/releases/tag/v2.2.7]. This can be +used to add data into a document that is not to be rendered, but which is still +needed for processing. + diff --git a/author/topics/sections/prefatory.adoc b/author/topics/sections/prefatory.adoc new file mode 100644 index 00000000..dcb15511 --- /dev/null +++ b/author/topics/sections/prefatory.adoc @@ -0,0 +1,129 @@ +--- +layout: author-docs +title: Prefatory clauses +--- + +== Prefatory clauses + +Prefatory sections are introductory sections that appear before the actual +content is shown, for example, the "`Foreword`" section. + + +=== General + +By default the single prefatory clause is identified with the pre-defined +section titles: + +* `Foreword` + + +=== Foreword + +A foreword is a full Metanorma AsciiDoc section, with the +title "`Foreword`"; this can be overruled in different flavours. + [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19] +A foreword may contain subclauses. + +[source,asciidoc] +-- +[[foreword]] +== Foreword +The Calendaring and Scheduling Consortium ("`CalConnect`") is a global non-profit +organization with the aim to facilitate interoperability of technologies across +user-centric systems and applications... + +=== Foreword subclause + +More foreword... +-- + +[NOTE] +==== +Metanorma AsciiDoc also supports a simple foreword clause syntax, using the +AsciiDoc preamble (any text between the document header and the first section +header). This syntax is restrictive (it requires there to be no preceding +clauses and no subclauses), and is now deprecated. + +The example below specifies the `.Foreword` title to the foreword in the source. +(Strictly speaking, this is the caption of the first paragraph in the foreword, +but it is used as the foreword header since the Foreword must precede any +AsciiDoc section headers.) + +Metanorma will supply the "`Foreword`" title if no such title is given. + +[source,asciidoc] +-- +[[foreword]] +.Foreword + +The Calendaring and Scheduling Consortium ("`CalConnect`") is a global non-profit +organization with the aim to facilitate interoperability of technologies across +user-centric systems and applications... +-- +==== + +=== Arbitrary prefatory clauses + +Arbitrary prefatory clauses are allowed in some flavors, and are disallowed +but "`accepted`" for encoding in certain flavors for backwards compatibility reasons. + +NOTE: Most flavors specify requirements on preface sections. Most flavors specify +mandatory and optional preface sections, while some completely disallow arbitrary +preface sections. + +[example] +In ISO only the "`Foreword`" is allowed -- arbitrarily named +preface sections are prohibited, in accordance with ISO Directives Part 2. + + +Any section detected as the "`Foreword`", or labelled as "`Introduction`", +"`Acknowledgements`" [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19], or +"`Abstract`", will be inserted into the document preface. + +Any other first-level clauses tagged with the role attribute +`[.preface]` are also moved into the document preface + [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.3.19]. + +If these prefatory sections are provided, they will be displayed in the following default ordering: + +* "`Abstract`" +* "`Foreword`" +* "`Introduction`" +* Preface clauses. Any prefatory clauses that don't fit the other specially "`named`" sections will be placed here. +* "`Acknowledgments`" + +[example] +.Automatic rendering order for prefatory clauses +==== +This source: + +[source,asciidoc] +-- +// tagged as the "`abstract`" +[.preface,heading=abstract] +== Executive summary + +Widget manufacture has proven profitable until recent times, when increased +competition has forced a reevaluation... + +// tagged as the "`acknowledgements`" +[.preface,heading=acknowledgements] +== Organizational contributors + +The following organizations have contributed valuable resources and expertise +for the completion of this standard... + +// tagged as normal +[.preface] +== Note for draft + +This is not an international standard, please be aware of the responsibilities +that come with application of this document... +-- + +Will be rendered in this order despite the input order: + +* "`Executive summary`" +* "`Note for draft`" +* "`Acknowledgments`" +==== \ No newline at end of file diff --git a/author/topics/sections/symbols_abbrev.adoc b/author/topics/sections/symbols_abbrev.adoc new file mode 100644 index 00000000..25e9aa56 --- /dev/null +++ b/author/topics/sections/symbols_abbrev.adoc @@ -0,0 +1,37 @@ +--- +layout: author-docs +title: Symbols and abbreviations +--- + +== Symbols and abbreviations + +=== General + +The symbols and abbreviations section is identified with the pre-defined +section titles: + +* `Symbols and abbreviated terms` +* `Symbols` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] +* `Abbreviated terms` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.5.0] + +=== Format + +Symbols and Abbreviations sections are expected to be simple definition lists +(http://asciidoctor.org/docs/user-manual/#labeled-list["`labelled lists`"] +in AsciiDoc nomenclature). + +Metanorma takes care of sorting the symbol entries in the order prescribed by +ISO/IEC DIR 2, provided the symbols are in AsciiMath. + +NOTE: Sorting MathML and LaTeX math entries is not currently supported. + +The syntax of the section is: + +[source,adoc] +---- +== Symbols and abbreviations + +symbol1:: text1 +symbol2:: text2 +stem:[symbol3]:: text3 +---- diff --git a/author/topics/sections/toc.adoc b/author/topics/sections/toc.adoc new file mode 100644 index 00000000..12b2ff45 --- /dev/null +++ b/author/topics/sections/toc.adoc @@ -0,0 +1,159 @@ +--- +layout: author-docs +title: Table of contents +--- +== Table of contents + +=== General + +A table of contents is provided at the start of a Metanorma document rendering, +either as: + +* prefatory material in electronic document formats (PDF, Word); or +* a sidebar in the HTML output. + +This table is typically a listing of all clauses of the document, and runs two +levels deep. + +In some flavours, a separate table of contents is inserted for figures, tables, +and recommendations. + + +=== Output formats + +Metanorma generates a table of contents automatically for Word, HTML, and PDF +output based on clause headings. + +* In Word, it takes the form of a normal Word Table of Contents. After +generating the Word output, the page numbers are not populated. You need to +refresh the table of contents by right-clicking on a field and choosing `Update +Field`. + +* In HTML, the table of contents takes the form of a side panel. + +* In PDF, it takes the form of an introductory table of contents. + + +=== Document attributes + +By default, the table of contents includes two levels of heading. + +More levels of heading can be set by using the document attribute `:toclevels:`. + +e.g. `:toclevels: 3` for three levels of heading included. + +The number of levels of heading to include can be set separately for HTML/PDF +and for DOC, by using the document attributes `:htmltoclevels:` and +`:doctoclevels:`. + + + +=== Using the `toc` command to generate a ToC + +A manual table of contents command has been added to +Metanorma [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5]. + +This is intended for a local table of contents, e.g., at the start of an +appendix. + +The table of contents `toc` command is utilized as follows. + +[source,adoc] +---- +toc:["xpath1:depth1","xpath2:depth2","xpath3:depth3"...] +---- + +Where, + +* `depth` is a number indicating the depth of indentation of the ToC +entry (default value `1`) + +* `xpath` is the XPath of the title being indexed in the Metanorma XML. + +For instance, in the following command: + +[source,adoc] +---- +toc:["//clause[@id = 'clause1'\]/clause/title","//clause[@id = 'clause1'\]/clause/clause/title:2"] +---- + +* all titles of subclauses of the clause with ID `clause1` are at the first + depth level of the manual table of contents (defaults to depth `1`) + +* all titles of sub-subclauses of the clause with ID `clause1` are at the second + depth level of the manual table of contents + +This means that the table of contents will have of the first-level clause with +ID `clause1`, running three levels deep. + + +=== Manually specifying a ToC + +A manual table of contents can also be provided as a clause of type +`toc` [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.7] +without using the `toc` command. + +Any table of contents entries within that manual table of contents are expected +to be provided as cross-references within unordered lists. + +The table of contents can contain subclauses, each with its own list of +cross-references, and other text. + +[example] +.Example of manually specifying a ToC +====== +[source,adoc] +---- +[type=toc] +=== Table of contents + +This is a table of contents. + +==== First subsection + +* <> +* <> + +==== Second subsection + +* <> +* <> +---- +====== + +=== Variant titles + +Clauses in Metanorma normally have only one title, and that title is used to +identify the clause in the table of contents. + +However, a manually created table of contents can make use of variant titles +instead. + +Variant titles [added in +https://github.com/metanorma/metanorma-standoc/releases/tag/v1.10.5] are entered +as paragraphs with a `variant-title` role attribute within a clause, as follows: + +[source,adoc] +---- +=== Proper title + +[.variant-title,type=toc] +This is the variant title + +Text of section. +---- + +Variant titles are not rendered in the body of the text. However, any variant +titles of type `toc` are used instead of the title as the entry text for a +manual table of contents. + +NOTE: Of course, if an explicit cross-reference text is given in a `toc` clause, +that takes priority. + +Variant titles are also used to generate the automated all-of-document table of +contents for HTML and PDF +documents [added in https://github.com/metanorma/isodoc/releases/tag/v1.8.5]. +They are not used in Word DOC output, because tables of contents for Word +documents are generated dynamically from the current heading. + +Variant titles are not currently used to generate the tables of other entities. diff --git a/author/topics/troubleshooting.adoc b/author/topics/troubleshooting.adoc new file mode 100644 index 00000000..acb2df5c --- /dev/null +++ b/author/topics/troubleshooting.adoc @@ -0,0 +1,267 @@ +--- +layout: author-docs +title: Troubleshooting +--- +tag::tutorial[] +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. + +== 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. + +.Example for a modular document setup +[source,Asciidoc] +==== +`Header with Metadata...`` + +`//include::sections/00-foreword.adoc[]` + +`include::sections/01-introduction.adoc[]` +`include::sections/02-scope.adoc[]` + +... +==== + +=== 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. + +end::tutorial[] +The following sections discuss common errors and how to fix them. + +== The document won't build - Compilation errors + +Compilation failures can happen due to installation or markup errors. +Hopefully, the compilation message will provide us with a clear insight of the cause of the failure. The first error line usually tells us the cause of the failure. + +Before looking at installation or markup errors, make sure you are running the build command in the place where your document is placed. + +.Example for a failed build because of the wrong location +[source,shell] +---- +user@machine my-standard % metanorma document.adoc <1> +Error: Specified input file 'document.adoc' does not exist. + +user@machine sources % metanorma document.adoc <2> +---- +<1> When we try to run Metanorma in the place that doesn't contain the actual document, it says that the document doesn't exist. +<2> Go to the folder that contains the document and run the build command again. + +=== Installation errors +Metanorma uses Ruby gems - small software packets that contain a certain function - to build Metanorma documents. For example, the `metanorma-iso` gem processes ISO standards. +To manage dependencies, Metanorma uses the tool https://bundler.io/v1.12/[Bundler]. + +To successfully compile a document, you need to install all gems Metanorma uses and make sure they are up-to-date. Normally, all relevant gems are installed if you followed the https://www.metanorma.org/install/[Installation guide]. + +To *install* all relevant gems: + +. Go to root folder of the directory in which your Metanorma project sits. + +TIP: You can move into another directory using the "change directory" command (`cd`). + +. Run `bundle install` + +Bundler fetches and installs the missing gems. + +To *update* outdated gems run `bundle-update` in your project directory. + +tag::no-compile-markup[] +=== Markup errors +Metanorma can't compile a document, when required information is missing or there are markup errors. + +==== 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. + +* 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. + +* Metadata specific to your organization. Check the https://www.metanorma.org/flavors/[flavor documentation] to make sure you've entered the metadata correctly. + +==== A single double quotation mark inside of a stem block +Double quotation marks are used in stem blocks to denote normal text, e.g.: `\stem:["normal text"]` +An odd number of double quotation marks inside a stem block will provoke a compilation error. + +For example, `\stem:["normal text""]` leads to the following compilation error: + +[source] +---- +... + from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/metanorma-cli-1.4.6/exe/metanorma:20:in `' + from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `load' + from C:/tools/ruby25/lib/ruby/gems/2.5.0/bin/metanorma:23:in `
' +parsing: "normal text"" +undefined method `[]' for nil:NilClass +---- + +==== An external file is not found +Metanorma can't compile a document when a reference to an external file cannot be found (i.e., an image or any other type of file). The error message will be explicit on which file. +You can solve the roblem by checking the specified location of the file. + +==== Two or more cross-references have the same anchor +If two or more cross-references have the same anchor, the document won't build and the error message will be clear on the reason. + +.Example of the same anchor name +[source,asciidoc] +---- +[[anchor1]] +== Section 1 +... + +[[anchor1]] +== Section 2 +... +---- + +To solve this problem, rename the anchor. Check your document against any references for the anchor that you changed and update them. +end::no-compile-markup[] + +== The document builds, but looks odd + +tag::rendering-errors[] + +=== Rendering errors +The main cause for rendering errors are markup errors which can lead to unexpected rendering results. +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. + +==== 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. + +Look for the beginning of the issue, go to the markup, and check out the delimiting characters of the blocks. + +.Examples of faulty blocks +[source, Asciidoc] +---- + +[source,Asciidoc] +=== <1> +image::../assets/image.png[] +=== + +|== <2> +|Name of Column 1 +|Name of Column 2 + +|Cell in column 1, row 1 +|Cell in column 2, row 1 + +|Cell in column 1, row 2 +|Cell in column 2, row 2 +|--- <3> + +---- +<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. +<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: + +* 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. + +end::rendering-errors[] + +==== Index term is showing up multiple times +If an index term that only should appear once, appears several times, check the parentheses used in the index entries for this term. +The syntax for index entries looks like this: + +[source, Asciidoc] +==== +Visible index terms: `\((Level 1 index term))` + +Hidden index terms: `(\((Level 1 index term, Level 2 index term, Level 3 index term)))` +==== + + +=== Cross-reference errors + +==== Incorrect format of reference anchor +Cross-reference anchors cannot begin with numbers, underscores, hyphens or any other special characters. If they do, they will not be processed in compilation and will certaintly lead to rendering errors in the section titles. Anchors must begin with a letter or an underscore and can not contain any special character other than hyphens and underscores. + +.Example for incorrect anchor names +[source,asciidoc] +---- +// Examples of incorrect anchors in references + +* [[[123anchor1,identifier 1]]], ... // Anchors cannot begin with a number + +* [[[_anchor2,identifier 2]]], ... // Anchors cannot begin with underscores or hyphens + +* [[[#anchor3,identifier 3]]], ... // Anchors cannot begin with any special character. Just letters. +---- + +Also make sure to use the same keyword for references. If the compiler finds a reference without a matching anchor, it will not process the reference. + +[source, Asciidoc] +---- +[[anchor1234]] +<> + +Error message: No label has been processed for ID anchor1432 +---- + +==== A reference auto-fetch failure +When a reference https://www.metanorma.org/author/topics/document-format/bibliography/#autofetch[auto-fetching] process fails, compilation failure may happen. + +The Metanorma team is constantly searching and solving issues related with the automatic importation of bibliographic entries. +Instead of waiting for a bugfix, you can apply a quick workaround. You can disable the automatic look-up of the individual reference by enclosing its identifier with `nofetch()`. + +For example, let's supose we have an issue with the reference `ITU-R BT.2267-10`. +Its AsciiDoc markup would correspond to: + +[source,asciidoc] +---- +[bibliography] +== References + +* [[[bt2267-10,ITU-R BT.2267-10]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._ +---- + +and gives us a compilation failure message of: + +[source] +---- +... +[relaton-itu] ("ITU-R BT.2267-10") fetching... +C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:440:in `block in symbolize': undefined method `to_sym' for 404:Integer (NoMethodError) +Did you mean? to_s + from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `each' + from C:/tools/ruby25/lib/ruby/gems/2.5.0/gems/relaton-bib-1.7.4/lib/relaton_bib/hash_converter.rb:439:in `reduce' +... +---- + +To solve issues with automatic lookup, we can set the `nofetch()` attribute: + +.Example of disabled automatic lookup for one bibliographic entry +[source,asciidoc] +==== +[bibliography] +== References + +* [[[bt2267-10,nofetch(ITU-R BT.2267-10)]]], Report ITU-R BT.2267-10 (2019), _Integrated broadcast-broadband systems._ +==== + +=== Errors that are bugs + +Metanorma is under continuous development, so it is possible to face an error that you can not fix because it is a bug. If you need help with a persisting error or if you found a bug, please create a new issue on Github in your organization's repository (`metanorma-ORGNAME`), for example `metanorma-iso`. + + +* https://github.com/metanorma[Metanorma Github] diff --git a/author/topics/writing-asciidoc.adoc b/author/topics/writing-asciidoc.adoc index 4e921a05..f3cab295 100644 --- a/author/topics/writing-asciidoc.adoc +++ b/author/topics/writing-asciidoc.adoc @@ -32,10 +32,10 @@ alongside this guidance. We have also published four blog entries on how to author a Metanorma document, step by step: -* https://www.metanorma.org/blog/2018-12-11-writing-metanorma-in-asciidoc/[Part 1] -* https://www.metanorma.org/blog/2018-12-15-writing-metanorma-in-asciidoc-2/[Part 2] -* https://www.metanorma.org/blog/2018-12-16-writing-metanorma-in-asciidoc-3/[Part 3] -* https://www.metanorma.org/blog/2019-01-15-writing-metanorma-in-asciidoc-4/[Part 4] +* link:/blog/2018-12-11-writing-metanorma-in-asciidoc/[Part 1] +* link:/blog/2018-12-15-writing-metanorma-in-asciidoc-2/[Part 2] +* link:/blog/2018-12-16-writing-metanorma-in-asciidoc-3/[Part 3] +* link:/blog/2019-01-15-writing-metanorma-in-asciidoc-4/[Part 4] == Recommended text editors diff --git a/builder/topics/metadata-and-boilerplate.adoc b/builder/topics/metadata-and-boilerplate.adoc index f3f996d2..d6df8c78 100644 --- a/builder/topics/metadata-and-boilerplate.adoc +++ b/builder/topics/metadata-and-boilerplate.adoc @@ -385,11 +385,13 @@ or not depends on the value of `bibdata/status`.) * Under the `metanorma/*` directory of the gem: -** The Metanorma predefined text file (`boilerplate.xml`) +** The Metanorma predefined text file (`boilerplate.xml`, `boilerplate.adoc`) [[boilerplate]] == Predefined text +=== XML + The `boilerplate` element in Metanorma XML follows after `bibdata`, and contains text that is repeatedly included in each instance of the document class, and that outlines the rules under which the document @@ -440,6 +442,10 @@ introductory page template; ** `
` appears in the title page template for the flavour; ** the CSS styling for the front page draft warning is styled as `boilerplate-license`. +A user-supplied boilerplate file need not provide all four statements [added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.8.2]. +If the user-supplied element is missing an element in the default for the flavour, the default is retained. +If the element is to be deleted, provide it as an empty title. + The following predefined text from metanorma-csa exemplifies all four statements in a predefined text, and its processing as a Liquid template. @@ -454,7 +460,7 @@ and its processing as a Liquid template. {% if unpublished %} - + Warning for Drafts

This document is not a CSA Standard. It is distributed for review and @@ -495,6 +501,121 @@ and its processing as a Liquid template. ---- +The following user-provided predefined text will delete the license statement, and override the legal statement, +leaving the copyright statement and feedback statement of the flavour alone: + +[source,xml] +---- + + + + + +

All rights reserved. Unless otherwise specified, no part of this + publication may be reproduced or utilized otherwise in any form or by any + means, electronic or mechanical, including photocopying, or posting on the + internet or an intranet, without prior written permission. Permission can + be requested from the address below. +

+ + + +---- + +=== ADOC + +Predefined text can also be specified in Metanorma Asciidoc, with the file suffix `.adoc` +[added in https://github.com/metanorma/metanorma-standoc/releases/tag/v2.4.6]. The following special +processing rules apply: + +* Top-level clauses ending in `-statement` are converted into the equivalent `boilerplate` tags; so +`== copyright-statement` corresponds to Metanorma XML ``. +* The Asciidoctor is a Liquid template, just as for XML, so `{{ ... }}` is reserved for Liquid, and cannot +be used for Metanorma Asciidoc concepts. The Asciidoc is processed by Liquid before it is passed on for processing. +* Clauses in predefined text often do not have clause titles; as usual for Asciidoc, introduce such titles with +`=== {blank}`. +* Clauses in Asciidoctor with no title and no user-assigned anchor are automatically assigned an anchor +of the form `_{n}`, where `{n}` is an integer. In order to prevent those anchors colliding in the boilerplate and +the main document, we overwrite any such anchors in the predefined text with the normal Metanorma default, +`_` followed by a GUID. Do not use `_{n}` as an anchor in any of your predefined text. +* Also be on the lookout +for any clauses with identical titles in your predefined text and your main document; if no user-defined anchor +is supplied, they will end up with the same title. To prevent that, the simplest thing to do is to provide +user-defined anchors for all titled clauses in the predefined text. +* The values that populate Liquid templates in Metanorma are in Metanorma XML, if they contain any formatting; +Metanorma automatically treats Asciidoc Liquid variables as Metanorma XML passthrough values. For example, +the `pub-address` document variable may be specified as document attribute as: ++ +[source,adoc] +---- +:pub-address: 1 John St + \ +London +---- ++ +-- +But its value in Liquid will be `1 John St
London`, since Liquid interpolation is developed for Metanorma XML. +Metanorma will treat any instance of `{{ pub_address}}` in Asciidoc predefined text as `pass:[{{pub_address}]` +(i.e. when converting the Asciidoc predefined text to Metanorma XML, the contents of `{{pub_address}}` will be left alone.) +-- + +The following is the Asciidoctor equivalent of the `boilerplate` Metanorma XML just given. This is for +a complete boilerplate document: + +[source,adoc] +---- +== copyright-statement +=== {blank} +© {{ docyear }} Cloud Security Alliance, LLC. + +{% if unpublished %} +== license-statement +[[draft-warning]] +=== Warning for Drafts + +This document is not a CSA Standard. It is distributed for review and +comment, and is subject to change without notice and may not be referred to as +a Standard. Recipients of this draft are invited to submit, with their +comments, notification of any relevant patent rights of which they are aware +and to provide supporting documentation. +{% endif %} + +== legal-statement +=== {blank} +All rights reserved. Unless otherwise specified, no part of this +publication may be reproduced or utilized otherwise in any form or by any +means, electronic or mechanical, including photocopying, or posting on the +internet or an intranet, without prior written permission. Permission can +be requested from the address below. + +== feedback-statement +=== {blank} +Cloud Security Alliance + +[align="left"] +2212 Queen Anne Ave N + +Seattle + +WA 98109 + +United States of America + + + +mailto:copyright@cloudsecurityalliance.com[copyright@cloudsecurityalliance.com] + +https://www.cloudsecurityalliance.com[www.cloudsecurityalliance.com] +---- + +And this will do a partial update, as above: + +[source,adoc] +---- +== license-statement + +== legal-statement +=== {blank} +All rights reserved. Unless otherwise specified, no part of this +publication may be reproduced or utilized otherwise in any form or by any +means, electronic or mechanical, including photocopying, or posting on the +internet or an intranet, without prior written permission. Permission can +be requested from the address below. +---- + == Cover page notes Metanorma provides a mechanism for notes and admonitions to appear on the cover diff --git a/flavor-quickstart-steps.adoc b/flavor-quickstart-steps.adoc index baee7033..dfbcfebe 100644 --- a/flavor-quickstart-steps.adoc +++ b/flavor-quickstart-steps.adoc @@ -54,7 +54,7 @@ as well as the AsciiDoc syntax reference. == Implementation {% if include.flavor.implemented_by %} -* link:/software/{{ include.flavor.implemented_by }}/[Ruby gem “{{ include.flavor.implemented_by }}”] +* link:/software/{{ include.flavor.implemented_by }}/[Ruby gem "{{ include.flavor.implemented_by }}"] implements the {{ include.flavor.title }} flavor of Metanorma, building on top of link:/software/metanorma/[core Metanorma library]. {% endif %} diff --git a/nav-links.html b/nav-links.html index 33f92502..d9109254 100644 --- a/nav-links.html +++ b/nav-links.html @@ -1,23 +1,21 @@ {% assign contact_link = "mailto:" | append: site.contact_email %}
- +
-{% include nav-page-link.html htmlclass="install" url="/install/" title="Install" active_for_nested=true %} +{% include nav-page-link.html htmlclass="installation" url="/installation/" title="Install Guide" active_for_nested=true %} -{% include nav-page-link.html htmlclass="author" url="/author/" title="Authoring" active_for_nested=true %} +{% include nav-page-link.html htmlclass="tutorial" url="/tutorials/" title="Tutorials" 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="software" url="/software/" title="Software" active_for_nested=true %} +{% include nav-page-link.html htmlclass="docs" url="/docs/" title="Docs" active_for_nested=true %} -{% include nav-page-link.html htmlclass="specs" url="/specs/" title="Specs" 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="flavors" url="/flavors/" title="Flavors" active_for_nested=true %} -{% include project-nav.html %} + {% include nav-page-link.html htmlclass="blog" url="/blog/" title="Blog" active_for_nested=true %} - + diff --git a/reference_docs/Ref-ISO-document-attributes.adoc b/reference_docs/Ref-ISO-document-attributes.adoc new file mode 100644 index 00000000..634bfca6 --- /dev/null +++ b/reference_docs/Ref-ISO-document-attributes.adoc @@ -0,0 +1,9 @@ +--- +layout: +tags: ["flavor:ISO", "type: Document Attributes"] +title: ISO document attributes +description: This page contains the complete Metanorma ISO document attributes specification. +--- + +// TO DO: Create a Script that reads standoc_document_attributes.yaml + flavor YAML file and render a complete reference. + diff --git a/reference_docs/Ref-standoc-document-attributes.adoc b/reference_docs/Ref-standoc-document-attributes.adoc new file mode 100644 index 00000000..8348dc69 --- /dev/null +++ b/reference_docs/Ref-standoc-document-attributes.adoc @@ -0,0 +1,9 @@ +--- +title: Document attributes reference +description: Describes all document attributes in a standard Metanorma document. +tags: ["flavor:Standard", "type: Document Attributes"] +layout: +description: This reference contains all document attributes you can use in a metanorma document, based on the standard document model (Standoc). These attributes are valid all flavors. However, many flavors need more specific document attributes and have added them to their document model. For a complete flavor-documentation, visit the Flavors[https://www.metanorma.org/flavors/] page. +--- + +// TO DO: Create a Script that reads standoc_document_attributes.yaml and renders a complete reference. + Fix front-matter diff --git a/reference_docs/YAML_models/calconnect_document_attributes.yaml b/reference_docs/YAML_models/calconnect_document_attributes.yaml new file mode 100644 index 00000000..30b98fdb --- /dev/null +++ b/reference_docs/YAML_models/calconnect_document_attributes.yaml @@ -0,0 +1,56 @@ +version: v3.4.5 #Verify versions + +inherits_from: + # Also may be referred to as “parent flavor” + flavor: standoc + version: v1.x.x + +document_attributes: +#--- Document info ---# + docnumber: + tags: ["Document info"] + title: "Document number" + description: "CalConnect document number, as allocated by TCC." + + status: + tags: ["Document info"] + title: "Status" + description: | + The status of the document. Synonym: `:docstage:`. + value_spec: "enum: proposal, working-draft, committee-draft, draft-standard, final-draft, published, withdrawn" + + doctype: + tags: ["Document info"] + title: "Document type" + description: | + The type of the document. Can be one of: + + + -- + standard:: Standard (no suffix on identifier; e.g. `CC 1`) + directive:: Directive (suffix `DIR`, e.g. `CC/DIR 1`) + guide:: Guide (suffix `Guide`) + specification:: Specification (suffix `S`) + report:: Report (suffix `R`) + administrative:: Administrative (suffix `A`) + amendment:: Amendment (suffix `Amd`) + technical corrigendum:: Technical Corrigendum (suffix `Cor`) + advisory:: Advisory (suffix `Adv`) + -- + value_spec: "enum: standard, directive, guide, specification, report, administrative, amendment, technical corrigendum, advisory" + + technical-committee: + tags: ["Document info"] + title: "Technical committee" + description: | + Name of the relevant CSD technical committee. + + A second relevant CSD technical committee (and other committees) are added as `_2`, `_3`, `_4`...​ + declaration: ":technical-committee:, :technical-committee{_i}:" + + technical-committee-type: + tags: ["Document info"] + title: "Technical committee type" + description: | + Type of the relevant CSD technical committee: `technical`, `provisional`. + + A second relevant CSD technical committee (and other committees) are added as `_2`, `_3`, `_4`... + required: true + declaration: ":technical-committee-type:, :technical-committee-type{_i}:" diff --git a/reference_docs/YAML_models/iec_document_attributes.yaml b/reference_docs/YAML_models/iec_document_attributes.yaml new file mode 100644 index 00000000..663022ee --- /dev/null +++ b/reference_docs/YAML_models/iec_document_attributes.yaml @@ -0,0 +1,127 @@ +version: v3.4.5 #Verify versions + +inherits_from: + # Also may be referred to as “parent flavor” + flavor: standoc + version: v1.x.x + +document_attributes: +#--- Parts and subparts ---# + partnumber: + tags: [""] + title: "Part number" + description: | + IEC documents can have both parts and subparts, unlike ISO documents which only supports parts. + + Both `{part}` and `{subpart}` only accept numerals. + value_spec: "other: `{part}` or `{part}`-`{subpart}`" + +#--- Document relations ---# + translated-from: + tags: ["Document relations"] + title: "Translated from" + description: | + Document identifier that the current document is a translation of. + + IEC documents can be translated by IEC-CO and tagged with the `translated-from` attribute. This is used to derive the correct status code. + more_information: "See link:/author/ref/document-attributes[general Metanorma document attributes] for more information." + +#--- Document type ---# + doctype: + tags: ["Document info"] + title: "Document type" + description: | + Type of document. + + Unlike ISO, IEC does not have `international-workshop-agreement`, and does have `interpretation-sheet`." + value_spec: "enum: international-standard, technical-specification, technical-report, publicly-available-specification, guide, interpretation-sheet" + required: true + + +#--- Project stage and substage of document ---# + docstage: + tags: ["Document info"] + title: "Document stage" + description: "Project stage code of document." + more_information: | + The codes in the first entry form are drawn from the + https://www.iso.org/stage-codes.html[ISO International Harmonized Stage Codes]. + + The mapping to IEC stage codes is taken from + https://www.iec.ch/members_experts/refdocs/iec/isoiecdir1-consolidatediecsup%7Bed15.0.RLV%7Den.pdf[ISO/IEC DIR 1:2019 + IEC SUP:2019, Annex SH], + updated against the current discussion of stage codes in + https://www.iec.ch/standardsdev/resources/processes/stage_codes.htm[IEC Processes & Procedures -- Stage Codes] and + https://www.iec.ch/standardsdev/resources/processes/workflows.htm[IEC Processes & Procedures -- Workflow]. + required: true + example: | + Following is a BPUB document in final proof (ISO stage 60, substage 00): + + [source,asciidoc] + ---- + :docstage: 60 + :docsubstage: 00 + ---- + + and this, is an NFDIS document that has reached approval stage, but it has been rejected, and will be returned to drafting: + + [source,asciidoc] + ---- + :docstage: 50 + :docsubstage: 92 + ---- + + docsubstage: + tags: ["Project stage and substage of document"] + title: "Document substage" + description: "Project substage code of document." + + stage: + tags: ["Project stage and substage of document"] + title: "Stage" + description: | + Project stage abbreviation. + + An IEC project stage abbreviation code entered under `:stage:` will be recognised, + and broken down into the corresponding ISO harmonized stage and substage codes + shown in the table automatically. + + For example, `:stage: ACD` is equivalent to setting `:docstage: 20` and `:docsubstage: 99`. + + In the case of A2CD... A9CD and 2CD... 9CD, the numeral value of the `:iteration:` attribute + will also be set accordingly. + + For example, `:stage: 8CD` is equivalent to setting `:docstage: 35`, `:docsubstage: 20` and `:iteration: 8`. + required: "don't know" + +#--- Cover page attributes ---# + accessibility-color-inside: + tags: ["Cover page attributes"] + title: "Accessibility color inside" + description: "Indication that document contains colour content." + value_spec: boolean + value_default: false + added_in_version: v1.2.10 + + price-code: + tags: ["Cover page attributes"] + title: "Price code" + description: "Price code group of publication, as documented in the https://www.iec.ch/members_experts/tools/pdf/IEC_DATA_FEEDS.pdf[IEC Data Feeds: Technical documentation document]." + added_in_version: v1.2.10 + + cen-processing: + tags: ["Cover page attributes"] + title: "CEN processing" + description: "CEN (European Committee for Standardization) processing." + value_spec: boolean + value_default: false + added_in_version: v1.2.11 + + secretary: + tags: ["Cover page attributes"] + title: "Secretary" + description: "Secretary of the secretariat." + added_in_version: v1.2.12 + + interest-to-committees: + tags: ["Cover page attributes"] + title: "Interest to committees" + description: "Draft is of interest to the following committees." + added_in_version: v1.2.12 diff --git a/reference_docs/YAML_models/ietf_v2_document_attributes.yaml b/reference_docs/YAML_models/ietf_v2_document_attributes.yaml new file mode 100644 index 00000000..2041f554 --- /dev/null +++ b/reference_docs/YAML_models/ietf_v2_document_attributes.yaml @@ -0,0 +1,487 @@ +version: v3.4.5 #Verify versions + +inherits_from: + # Also may be referred to as “parent flavor” + flavor: standoc + version: v1.x.x + +document_attributes: +#--- Document type ---# + doctype: + tags: ["Document info"] + title: "Document type" + description: | + Specifies document status. Choices: + + * `:doctype: internet-draft` sets the document as an Internet-Draft (default value): + ** `rfc@docName` will be set to the `:name:` attribute + * `:doctype: rfc` sets the document as an RFC: + ** `rfc@number` will be set to the `:name:` attribute. + value_default: internet-draft + +#--- Pre-processing options ---# + no-rfc-bold-bcp14: + tags: ["Pre-processing options"] + title: "No RFC bold BCP14" + description: "Override default assumption that boldface uppercase BCP14 word is to be rendered with `bcp14` tag." + value_spec: boolean + value_default: true + + smart-quotes: + tags: ["Pre-processing options"] + title: "Smart quotes" + description: | + Permit smart quotes, when they are specified explicitly in AsciiDoc (as `pass:['`...`']`, `pass:['`...`']`). When disabled, smart quotes are rendered as straight quotes, and Asciidoc's default conversion of straight apostrophes to smart is undone. + value_spec: boolean + value_default: true + + flush-caches: + tags: ["Pre-processing options"] + title: "Flush caches" + description: | + Delete and reload the caches of references to be included externally, and of workgroups, during processing of this document. + + The caches are stored in `~/.metanorma-ietf-biblio-cache.json` and `~/.metanorma-ietf-workgroup-cache.json`. + value_spec: boolean + value_default: false + +#--- Document info ---# + title: + tags: ["Document info"] + title: "Title of document" + description: "Title of document." + required: true + + abbrev: + tags: ["Document info"] + title: "Abbreviation of document" + description: "Abbreviation of document title. Usually the document name without the keyword `draft-`. RFC XML: `rfc/front/title@abbrev`." + required: true + + name: + tags: ["Document info"] + title: "Name of document" + description: | + Sets the document's name. This should be a number if + the document is an RFC, and a name (in the form of `draft-ietf-somewg-someprotocol-07`) + if it is an Internet-Draft. + When `doctype` is set to: + + * `internet-draft`: the value should be in the form `draft-ietf-somewg-someprotocol-07`. + ** RFC XML: `rfc@docName` + * `rfc`: the value should be a number like `7991` as described + in https://tools.ietf.org/html/rfc7991#section-2.47.6[here] + RFC XML: `rfc@number` + + NOTE: Usage here differs from usage in AsciiRFC v3. + required: true + + status: + tags: ["Document info"] + title: "Status" + description: | + Set the current status of this document. Synonym: `:docstage:`. + The following values are allowed: + + * `standard` (mapped in v2 to: `std`) + * `informational` (mapped in v2 to: `info`) + * `experimental` (mapped in v2 to: `exp`) + * `bcp` + * `historic` + + RFC XML `rfc@category` + + NOTE: Usage here differs from usage in AsciiRFC v3. + value_spec: "enum: standard, informational, experimental, bcp, historic" + + intended-series: + tags: ["Document info"] + title: "Intended series" + description: | + Set the intended series of this + document. For Internet Drafts, this indicates the intended series once the document is published as an RFC. For RFCs, this indicates the current status of the document. The following values are allowed: + + * `standard` (I.-D. only) (mapped in v2 to: `std`) + * `informational` (mapped in v2 to: `info`) + * `experimental` (mapped in v2 to: `exp`) + * `bcp` (I.-D. only) + * `bcp nnnn` (RFC only, where `nnnn` is the document number) + * `fyi` (I.-D. only) + * `fyi nnnn` (RFC only, where `nnnn` is the document number) + * `full-standard` (I.-D. only) (mapped in v2 to: `std`) + * `full-standard nnnn` (RFC only, where `nnnn` is the document number) (mapped in v2 to: `std`) + * `historic` + + RFC XML `front/@category` (`exp` and `historic` only supported for Internet Drafts; document number not used) + + NOTE: Usage here differs from usage in AsciiRFC v3. + required: true + + series-no: + tags: ["Document info"] + title: "Series number" + description: | + The document series is defined by the `category` attribute; + `seriesNo` is only applicable to the values _info_ ("FYI" series), + _std_ ("STD" series), and _bcp_ ("BCP" series). RFC XML v3 counterpart: `rfc@seriesNo` + + NOTE: This attribute is only available in AsciiRFC v3. + + submission-type: + tags: ["Document info"] + title: "Submission type" + description: | + Set document submission type for this document from the predefined values. + + RFC XML: `rfc@submissionType` + NOTE: Usage here differs from usage in AsciiRFC v3. + value_spec: "enum: IETF, independent, IAB, IRTF" + value_default: IETF + + ipr: + tags: ["Document info"] + title: "IP status" + description: "Intellectual property status of document. RFC XML: `rfc@ipr`." + required: true + value_default: trust200902 + more_information: "See https://tools.ietf.org/html/rfc7991#section-2.45.5[RFC 7991]." + + ipr-extract: + tags: ["Document info"] + title: "IPR extract" + description: "Identifies a section that can be extracted from text. RFC XML: `rfc@iprExtract`." + more_information: "See https://tools.ietf.org/html/rfc7991#section-2.45.6[RFC 7991]" + + obsoletes: + tags: ["Document info"] + title: "Obsoletes" + description: "A comma-separated list of RFC numbers or Internet-Draft names that this document obsoletes. RFC XML: `rfc@obsoletes`." + value_spec: comma-list + + updates: + tags: ["Document info"] + title: "Updates" + description: "A comma-separated list of RFC numbers or Internet-Draft names that this document updates. RFC XML: `rfc@updates`." + value_spec: comma-list + + submission-type: + tags: ["Document info"] + title: "Submission type" + description: "Document stream of document described in https://tools.ietf.org/html/rfc7841[RFC7841]. RFC XML: `rfc@submissionType`." + value_spec: "enum: IETF, independent, IAB, IRTF" + value_default: IETF + + revdate: + tags: ["Document info"] + title: "Revision date" + description: "Latest revision date of document. Default value is current time. Accepts ISO 8601 date. Also accepts `YYYY` year, and `YYYY[-]MM` year/month. For consistency with AsciiDoc, `:revdate:` is given as an ISO 8601 date; the converter breaks it down into day, month name and year RFC XML: `front/date@day`, `front/date@month`, `front/date@year`." + value_default: "{current time}" + + area: + tags: ["Document info"] + title: "Area of document" + description: 'Comma delimited text on which IETF area this document relates to. Value should be either the full name or the abbreviation of one of the http://www.ietf.org/iesg/area.html[IETF areas]. RFC XML: `front/area`.' + + workgroup: + tags: ["Document info"] + title: "Workgroup" + description: "Comma delimited text on which IETF or IRTF workgroup or research group this document originates from. RFC XML: `front/workgroup`." + more_information: See https://tools.ietf.org/html/rfc7991#section-2.65[RFC 7991] + + keyword: + tags: ["Document info"] + title: "Keyword" + description: "Comma delimited text for singular keywords used for RFC index and metadata. RFC XML: `front/keyword`." + + xml-lang: + tags: ["Document info"] + title: "XML language" + description: "Set the document language. By default this is `en`. RFC XML: `rfc@xml:lang`." + + consensus: + tags: ["Document info"] + title: "Consensus" + description: | + Set document consensus for this document. The following values are allowed: + + * `false` (mapped in v2 to: `no`) + * `true` (mapped in v2 to: `yes`) + + RFC XML: `rfc@consensus`. + value_spec: boolean + +#--- Author info ---# + + lastname: + tags: ["Author info"] + title: "Lastname of author" + description: "Author's last name. Can set here instead of document header's '`Author`' line. RFC XML: `front/author@surname`." + declaration: ":lastname:, :lastname{_i}:" + + role: + tags: ["Author info"] + title: "Role of author" + description: "If `author` is supplied, the attribute is not populated. RFC XML: `front/author@role`." + declaration: ":role:, :role{_i}:" + value_spec: "enum: author, editor" + value_default: author + + organization: + tags: ["Author info"] + title: "Organization of author" + description: "Author's organization affiliation. RFC XML: `front/author/organization`." + declaration: ":organization:, :organization{_i}:" + value_default: "" + + organization_abbrev: + tags: ["Author info"] + title: "Organization abbreviation of author" + description: "Author's organization's abbreviation shown. RFC XML: `front/author/organization@abbrev`." + declaration: ":organization_abbrev:, :organization_abbrev{_i}:" + value_default: "" + +#--- Address attributes ---# + email: + tags: ["Address attributes"] + title: "Email of author" + description: "Email of author. RFC XML: `front/author/address/email`." + declaration: ":email:, :email{_i}:" + + fax: + tags: ["Address attributes"] + title: "Fax of author" + description: "Fax number of author. Deprecated in v3. RFC XML: `front/author/address/facsimile`." + declaration: ":fax:, :fax{_i}:" + + uri: + tags: ["Address attributes"] + title: "URI of author" + description: "URI of author. RFC XML: `front/author/address/uri`." + declaration: ":uri:, :uri{_i}:" + + phone: + tags: ["Address attributes"] + title: "Phone number of author" + description: "Author's phone number. Scheme-specific part of a `tel` URI (does not include the prefix `tel:`). RFC XML: `front/author/address/phone`." + declaration: ":phone:, :phone{_i}:" + more_information: "See https://tools.ietf.org/html/rfc3966#section-3[RFC3966 `global-number-digits`]" + + street: + tags: ["Address attributes"] + title: "Street address of author" + description: "Address of author, non-city/region/code/country portion. Multiple lines concatenated with `'\ '` will be split into separate `` elements. RFC XML: `front/author/address/postal/street`." + declaration: ":street:, :street{_i}:" + + city: + tags: ["Address attributes"] + title: "City of author" + description: "City portion of author's address. RFC XML: `front/author/address/postal/city`." + declaration: ":city:, :city{_i}:" + + region: + tags: ["Address attributes"] + title: "Region of author" + description: "Region, state or province portion of author's address. For US/CA the 2-letter state code. RFC XML: `front/author/address/postal/region`." + declaration: ":region:, :region{_i}:" + + country: + tags: ["Address attributes"] + title: "Country of author" + description: "Country of author's address. RFC XML: `front/author/address/postal/country`." + declaration: ":country:, :country{_i}:" + + code: + tags: ["Address attributes"] + title: "Postal code of author" + description: "Postal code of author's address. RFC XML: `front/author/address/postal/code`." + declaration: ":code:, :code{_i}:" + value_spec: number + +#--- Processing instructions for xml2rfc ---# + artworkdelimiter: + tags: ["Processing instructions for xml2rfc"] + title: "Artwork delimiter" + description: "When producing `txt` or `nroff` files, use this string to delimit artwork." + + artworklines: + tags: ["Processing instructions for xml2rfc"] + title: "Artwork lines" + description: "When producing txt or nroff files, add this many blank lines around artwork." + + authorship: + tags: ["Processing instructions for xml2rfc"] + title: "Authorship" + description: "Render author information." + + autobreaks: + tags: ["Processing instructions for xml2rfc"] + title: "Autobreaks" + description: "Automatically force page breaks to avoid widows and orphans (not perfect)." + + background: + tags: ["Processing instructions for xml2rfc"] + title: "Background image" + description: "When producing a HTML file, use this image." + + colonspace: + tags: ["Processing instructions for xml2rfc"] + title: "Colon space" + description: 'Put two spaces instead of one after each colon ("`:`") in txt or nroff files.' + + comments: + tags: ["Processing instructions for xml2rfc"] + title: "Comments" + description: "Render `` information." + + compact: + tags: ["Processing instructions for xml2rfc"] + title: "Compact" + description: "When producing a txt/nroff file, try to conserve vertical whitespace (the default value is the current value of the `rfcedstyle` PI)." + + docmapping: + tags: ["Processing instructions for xml2rfc"] + title: "Document mapping" + description: "Use hierarchical tags (e.g., `

`, `

`, etc.) for (sub)section titles." + + editing: + tags: ["Processing instructions for xml2rfc"] + title: "Editing" + description: "Insert editing marks for ease of discussing draft versions." + + emoticonic: + tags: ["Processing instructions for xml2rfc"] + title: "Emoticonic" + description: "Automatically replaces input sequences such as `|*text|` by, e.g., `text` in html output." + + footer: + tags: ["Processing instructions for xml2rfc"] + title: "Footer" + description: "Override the center footer string." + + header: + tags: ["Processing instructions for xml2rfc"] + title: "Header" + description: "Override the leftmost header string." + + inline: + tags: ["Processing instructions for xml2rfc"] + title: "Inline" + description: "If comments is "yes", then render comments inline; otherwise render them in an "Editorial Comments" section." + + iprnotified: + tags: ["Processing instructions for xml2rfc"] + title: "IPR notified" + description: "Include boilerplate from Section 10.4(d) of http://tools.ietf.org/html/rfc2026[RFC 2026]." + + linkmailto: + tags: ["Processing instructions for xml2rfc"] + title: "Generate mailto" + description: "Generate mailto: URL, as appropriate." + + linefile: + tags: ["Processing instructions for xml2rfc"] + title: "linefile" + description: "A string like "35:file.xml" or just "35" (file name then defaults to the containing file's real name or to the latest linefile specification that changed it) that will be used to override xml2rfc's reckoning of the current input position (right after this PI) for warning and error reporting purposes (line numbers are 1-based)." + + notedraftinprogress: + tags: ["Processing instructions for xml2rfc"] + title: "Note draft in progress" + description: 'Generates "(work in progress)", as appropriate.' + + private: + tags: ["Processing instructions for xml2rfc"] + title: "private" + description: "Produce a private memo rather than an RFC or Internet-Draft." + + refparent: + tags: ["Processing instructions for xml2rfc"] + title: "Ref parent" + description: "Title of the top-level section containing all references." + + rfcedstyle: + tags: ["Processing instructions for xml2rfc"] + title: "rfcedstyle" + description: | + Attempt to closely follow finer details from the latest observable RFC-Editor style so as to minimize the probability of being sent back corrections after submission. + + This directive is a kludge whose exact behavior is likely to change on a regular basis to match the current flavor of the month; presently, it will: + + * capitalize the adjective "`This`" in automatically generated headings, + * use the variant "`acknowledgement`" spelling instead of Merriam Webster's main "`acknowledgment`" dictionary entry, + * use the "`eMail`" spelling instead of Knuth's more modern "`email`" spelling, + * only put one blank line instead of two before top sections, + * omit "`Intellectual Property and Copyright Statements`" and "`Author's Address`" from the table of content, and + * not limit the indentation to a maximum tag length in `` sections. + + rfcprocack: + tags: ["Processing instructions for xml2rfc"] + title: "rfcprocack" + description: "If there already is an automatically generated Acknowledgement section, pluralize its title and add a short sentence acknowledging that xml2rfc was used in the document's production to process an input XML source file in RFC-2629 format." + + slides: + tags: ["Processing instructions for xml2rfc"] + title: "Slides" + description: "When producing a html file, produce multiple files for a slide show." + + sort-refs: + tags: ["Processing instructions for xml2rfc"] + title: "Sort references" + description: " Sort references alphabetically." + + strict: + tags: ["Processing instructions for xml2rfc"] + title: "Strict" + description: "Try to enforce the ID-nits conventions and DTD validity." + + subcompact: + tags: ["Processing instructions for xml2rfc"] + title: "Subcompact" + description: 'If compact is "yes", then you can make things a little less compact by setting this to "no" (the default value is the current value of the compact PI).' + + sym-refs: + tags: ["Processing instructions for xml2rfc"] + title: "Symbolic references" + description: "(`symrefs`) use anchors rather than numbers for references." + + text-list-symbols: + tags: ["Processing instructions for xml2rfc"] + title: "Text list symbols" + description: 'Modify the list of symbols used (when generated text) for list type="symbols". For example, specifying "abcde" will cause "a" to be used for 1st level, "b" for the 2nd level, etc, cycling back to the first character "a" at the 6th level. Specifying "o*" will cause the characters "o" and "*" to be alternated for each successive level.' + + toc-include: + tags: ["Processing instructions for xml2rfc"] + title: "ToC include" + description: "(`toc`) generate a table-of-contents." + + tocappendix: + tags: ["Processing instructions for xml2rfc"] + title: "ToC appendix" + description: "Control whether the word "Appendix" appears in the table-of-content." + + toc-depth: + tags: ["Processing instructions for xml2rfc"] + title: "ToC depth" + description: 'If `:toc-include:` is "yes", then this determines the depth of the table-of-contents.' + + tocindent: + tags: ["Processing instructions for xml2rfc"] + title: "ToC indent" + description: 'If `:toc-include:` is "yes", then setting this to "yes" will indent subsections in the table-of-contents.' + + tocnarrow: + tags: ["Processing instructions for xml2rfc"] + title: "ToC narrow" + description: "affects horizontal spacing in the table-of-content." + + tocompact: + tags: ["Processing instructions for xml2rfc"] + title: "ToC compact" + description: 'If `:toc-include:` is "yes", then setting this to "no" will make it a little less compact.' + + topblock: + tags: ["Processing instructions for xml2rfc"] + title: "topblock" + description: "Put the famous header block on the first page." + + useobject: + tags: ["Processing instructions for xml2rfc"] + title: "useobject" + description: "When producing a html file, use the html element with inner replacement content instead of the html element, when a source xml element includes an src attribute." diff --git a/reference_docs/YAML_models/ietf_v3_document_attributes.yaml b/reference_docs/YAML_models/ietf_v3_document_attributes.yaml new file mode 100644 index 00000000..9a0c3040 --- /dev/null +++ b/reference_docs/YAML_models/ietf_v3_document_attributes.yaml @@ -0,0 +1,573 @@ +version: v3.4.5 #Verify versions + +inherits_from: + # Also may be referred to as “parent flavor” + flavor: standoc + version: v1.x.x + +document_attributes: +#--- Document type ---# + doctype: + tags: ["Document info"] + title: "Document type" + description: | + Specifies document status. Choices: + + + * `:doctype: internet-draft` sets the document as an Internet-Draft (default value): + ** `rfc/front/seriesInfo@name` attribute will be set to _Internet-Draft_ + ** `rfc/front/seriesInfo@value` will be set to the value of `:name:` attribute, stripping any file suffixes, but including any draft number; e.g. `draft-ietf-somewg-someprotocol-07` + ** `rfc@docName` will be set to the `:docnumber:` attribute + * `:doctype: rfc` sets the document as an RFC: + ** `rfc/front/seriesInfo@name` attribute will be set to _RFC_ + ** `rfc/front/seriesInfo@value` will be set to the value of `:name:` attribute, stripping the initial `rfc-` prefix and any file suffixes + ** `rfc@number` will be set to the `:name:` attribute + value_spec: "enum: internet-draft, rfc" + value_default: internet-draft + +#--- Pre-processing options ---# + no-rfc-bold-bcp14: + tags: ["Pre-processing options"] + title: "No RFC bold BCP14" + description: "Override default assumption that boldface uppercase BCP14 word is to be rendered with `bcp14` tag." + value_spec: boolean + value_default: true + + smart-quotes: + tags: ["Pre-processing options"] + title: "Smart quotes" + description: | + Permit smart quotes, when they are specified explicitly in AsciiDoc (as `pass:['`...`']`, `pass:['`...`']`). When disabled, smart quotes are rendered as straight quotes, and Asciidoc's default conversion of straight apostrophes to smart is undone. + value_spec: boolean + value_default: true + + flush-caches: + tags: ["Pre-processing options"] + title: "Flush caches" + description: | + Delete and reload the caches of references to be included externally, and of workgroups, during processing of this document. + + The caches are stored in `~/.metanorma-ietf-biblio-cache.json` and `~/.metanorma-ietf-workgroup-cache.json`. + value_spec: boolean + value_default: false + + use-xinclude: + tags: ["Pre-processing options"] + title: "Use xinclude" + description: | + If present, references to IETF documents are handled as XIncludes as recommended by IETF's https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html["xml2rfc Frequently Asked Questions, 3.1"]. Otherwise, they are left as embedded XML. + + Setting this to `false` allows you to compile final output using `xmlrfc` with cached reference content without triggering its Internet-fetching functionality (https://www.rfc-editor.org/materials/FAQ-xml2rfcv3.html["xml2rfc Frequently Asked Questions, 3.2"]. + added_in_version: v2.0.8 + +#--- Document info ---# + title: + tags: ["Document info"] + title: "Title of document" + description: "Title of document. RFC XML: `rfc/front/title`." + required: true + + abbrev: + tags: ["Document info"] + title: "Abbreviation of document" + description: "Abbreviation of document title. Usually the document name without the keyword `draft-`. RFC XML: `rfc/front/title@abbrev`." + required: true + + asciititle: + tags: ["Document info"] + title: "Ascii title" + description: "ASCII version of the title, in case author wants to override the default ASCII equivalent generated by Ruby (through the https://github.com/pbhogan/sterile[sterile] gem)." + + name: + tags: ["Document info"] + title: "Name of document" + description: | + Sets the document's name. This should be a number if + the document is an RFC, and a name (in the form of `draft-ietf-somewg-someprotocol-07`) + if it is an Internet-Draft. + When `doctype` is set to: + + * `internet-draft`: the value should be in the form `draft-ietf-somewg-someprotocol-07`. + ** RFC XML: `rfc@docName` + * `rfc`: the value should be a number like `7991` as described + in https://tools.ietf.org/html/rfc7991#section-2.47.6[here] + RFC XML: `rfc@number` + + NOTE: Usage here differs from usage in AsciiRFC v2. + required: true + + status: + tags: ["Document info"] + title: "Status" + description: | + Set the current status of this document. Synonym: `:docstage:`. The following values are allowed: + + * `standard` + * `informational` + * `experimental` + * `bcp` + * `fyi` + * `full-standard` + + RFC XML: `front/seriesInfo[1]/@status`, `rfc@category`. + + NOTE: Usage here differs from usage in AsciiRFC v2. + value_spec: "enum: standard, informational, experimental, bcp, fyi, full-standard" + + intended-series: + tags: ["Document info"] + title: "Intended series" + description: | + Set the intended series of this document. Space delimited. + For Internet Drafts, this indicates the intended series once the document is published as an RFC. + For RFCs, this indicates the current status of the document. The following values are allowed: + + * `standard` (I.-D. only) + * `informational` + * `experimental` + * `bcp` (I.-D. only) + * `bcp nnnn` (RFC only, where `nnnn` is the document number) + * `fyi` (I.-D. only) + * `fyi nnnn` (RFC only, where `nnnn` is the document number) + * `full-standard` (I.-D. only) + * `full-standard nnnn` (RFC only, where `nnnn` is the document number) + * `historic` + + RFC XML: `front/seriesInfo[2]/@status`; + `front/seriesInfo[2]/@name = ""`; + `front/@category` (`exp` and `historic` only supported for Internet Drafts; document number not used). + + NOTE: This differs from usage in AsciiRFC v2. Metanorma-IETF takes care of any needed + translation between the v2 vocabulary (e.g. `info`) and the v3 vocabulary + (e.g. `informational`).' + value_spec: "enum: standard, informational, experimental, bcp, bcp nnnn, fyi, fyi nnnn, full-standard, full-standard nnnn" + + submission-type: + tags: ["Document info"] + title: "Submission type" + description: | + Set document submission type for this document from the predefined values. + + RFC XML: `rfc@submissionType` and `rfc/front/seriesInfo@stream`. + NOTE: Usage here differs from usage in AsciiRFC v2. + value_spec: "enum: IETF, independent, IAB, IRTF" + value_default: IETF + + ipr: + tags: ["Document info"] + title: "IPR" + description: | + Intellectual property status of document. See + https://tools.ietf.org/html/rfc7991#section-2.45.5[RFC 7991]. Defaults to `trust200902`. RFC XML: `rfc@ipr`. + + NOTE: Usage here differs from usage in AsciiRFC v2. + required: true + value_default: trust200902 + + ipr-extract: + tags: ["Document info"] + title: "IPR extract" + description: | + Identifies a section that can be extracted from text. See + https://tools.ietf.org/html/rfc7991#section-2.45.6[RFC 7991]. + RFC XML: `rfc@iprExtract`. + + NOTE: Usage here differs from usage in AsciiRFC v2. + + obsoletes: + tags: ["Document info"] + title: "Obsoletes" + description: "A comma-separated list of RFC numbers or Internet-Draft names that this document obsoletes. RFC XML: `rfc@obsoletes`." + value_spec: comma-list + + updates: + tags: ["Document info"] + title: "Updates" + description: "A comma-separated list of RFC numbers or Internet-Draft names that this document updates. RFC XML: `rfc@updates`." + value_spec: comma-list + + included-in: + tags: ["Document info"] + title: "included-in" + description: | + (RFC only) ISSN for this RFC document. Identifiers expected to be in form of `urn:issn:`. + RFC XML: `front/link[@rel = 'item']/@href`. + + + NOTE: The odd selection of `:included-in:` is in fact the closest match to the link type "item" used in RFC 7991. + + described-by: + tags: ["Document info"] + title: "Described by" + description: | + DOI for this RFC document. Identifiers expected to be in form + specified by https://tools.ietf.org/html/rfc7669[RFC7669]. + + RFC XML: `front/link[@rel = 'describedby']/@href`. + + derived-from: + tags: ["Document info"] + title: "Derived from" + description: "(Final Draft) Internet-Draft submitted to become published RFC. If these are IETF documents, they must be identified with the URL of the Internet Draft on the IETF-controlled web site that retains copies of Internet-Drafts. RFC XML: `front/link[@rel = 'convertedFrom']/@href`." + + instance: + tags: ["Document info"] + title: "Instance" + description: | + (Any status) URL for any alternate representation of this document. RFC XML: `front/link[@rel = 'alternate']/@href` + + NOTE: Formerly this was called `:equivalent:`. + added_in_version: v2.0.8 + + submission-type: + tags: ["Document info"] + title: "Submission type" + description: "Document stream of document described in https://tools.ietf.org/html/rfc7841[RFC7841]. Allowed values: `IETF` (default), `independent`, `IAB`, and `IRTF`. RFC XML: `rfc@submissionType`." + value_spec: "enum: IETF, independent, IAB, IRTF" + value_default: IETF + + revdate: + tags: ["Document info"] + title: "Revision date" + description: "Latest revision date of document. Default value is current time. Accepts ISO 8601 date. Also accepts `YYYY` year, and `YYYY[-]MM` year/month. For consistency with AsciiDoc, `:revdate:` is given as an ISO 8601 date; the converter breaks it down into day, month name and year RFC XML: `front/date@day`, `front/date@month`, `front/date@year`." + value_default: "{current time}" + + area: + tags: ["Document info"] + title: "Area of document" + description: 'Comma delimited text on which IETF area this document relates to. Value should "be either the full name or the abbreviation of one of the IETF areas as listed on ". See https://tools.ietf.org/html/rfc7991#section-2.4[here]. RFC XML: `front/area`.' + + workgroup: + tags: ["Document info"] + title: "Workgroup" + description: "Comma delimited text on which IETF or IRTF workgroup or research group this document originates from. RFC XML: `front/workgroup`." + more_information: See https://tools.ietf.org/html/rfc7991#section-2.65[here] + + xml-lang: + tags: ["Document info"] + title: "XML language" + description: "Set the document language. By default this is `en`. RFC XML: `rfc@xml:lang`." + + consensus: + tags: ["Document info"] + title: "Consensus" + description: | + Set document consensus for this document. The following values are allowed: + + * `false` + * `true` + + RFC XML: `rfc@consensus`. + value_spec: boolean + + index-include: + tags: ["Document info"] + title: "Index include" + description: | + Specifies whether formatter should include an index in generated files. If the source file has no `` elements, an index is never generated. + + RFC XML: `rfc@indexInclude` + + NOTE: This attribute is new in AsciiRFC v3 (RFC XML v3). + value_spec: boolean + value_default: true + + sort-refs: + tags: ["Document info"] + title: "Sort references" + description: | + Specifies whether the prep tool should sort references. + + RFC XML: `rfc@sortRefs` + + NOTE: This attribute is new in AsciiRFC v3 (RFC XML v3). + value_spec: boolean + value_default: false + + sym-refs: + tags: ["Document info"] + title: "Symbolic references" + description: | + Specifies whether formatter should use symbolic references (such as "`[RFC211]`") or not (such as "`[3]`"). + + RFC XML: `rfc@symRefs` + NOTE: This attribute is new in AsciiRFC v3 (RFC XML v3). + value_spec: boolean + value_default: true + + toc-include: + tags: ["Document info"] + title: "ToC include" + description: | + Specifies whether formatter should contain a table of contents. + RFC XML: `rfc@tocInclude` + + + NOTE: This attribute is new in AsciiRFC v3 (RFC XML v3). + value_spec: boolean + value_default: true + + toc-depth: + tags: ["Document info"] + title: "ToC depth" + description: | + Determines the depth of the table-of-contents; e.g. a value of `3` means three levels of heading are included. RFC XML: `rfc@tocDepth` + + + NOTE: This attribute is new in AsciiRFC v3 (RFC XML v3). + + show-on-front-page: + tags: ["Document info"] + title: "Show on front page" + description: | + Display organization of author on front page of IAB document. Introduced in Levkowetz' implementation notes. RFC XML: `organization/@showOnFrontPage`, applied to all organizations named in the document front matter. + + + NOTE: This attribute is new in AsciiRFC v3 (RFC XML v3). + value_spec: boolean + value_default: true + +#--- Author info ---# + + givenname: + tags: ["Author info"] + title: "Given name" + description: | + Given names of Author. Not used directly in RFC XML, but initials can be derived from them if not explicitly included. RFC XML: `front/author@initials`. + declaration: ":givenname:, :givenname{_i}:" + + surname: + tags: ["Author info"] + title: "Surname" + description: | + Author's last name. Can set here instead of document header's "`Author`" line. + + RFC XML: `front/author@surname`. + declaration: ":surname:, :surname{_i}:" + + role: + tags: ["Author info"] + title: "Role" + description: "Defaults to `author`. Possible values: `author`, `editor`. If `author` is supplied, the attribute is not populated. RFC XML: `front/author@role`." + declaration: ":role:, :role{_i}:" + value_spec: "enum: author, editor" + value_default: author + + affiliation: + tags: ["Author info"] + title: "Organization affiliation" + description: "Author's organization affiliation. RFC XML: `front/author/organization`." + declaration: ":affiliation:, :affiliation{_i}:" + value_default: "" + + affiliation_abbrev: + tags: ["Author info"] + title: "Organization abbreviation" + description: "Author's organization's abbreviation shown. RFC XML: `front/author/organization@abbrev`." + declaration: ":organization_abbrev:, :organization_abbrev{_i}:" + value_default: "" + +#--- Address attributes ---# + email: + tags: ["Address attributes"] + title: "Email" + description: "Email of author. RFC XML: `front/author/address/email`." + declaration: ":email:, :email{_i}:" + + fax: + tags: ["Address attributes"] + title: "Fax" + description: "Fax number of author. Deprecated in v3. RFC XML: `front/author/address/facsimile`." + declaration: ":fax:, :fax{_i}:" + + contributor-uri: + tags: ["Address attributes"] + title: "Contributor URI" + description: "URI of author. RFC XML: `front/author/address/uri`." + declaration: ":contributor-uri:, :contributor-uri{_i}:" + + phone: + tags: ["Address attributes"] + title: "Phone number" + description: "Author's phone number. Scheme-specific part of a `tel` URI (does not include the prefix `tel:`). See https://tools.ietf.org/html/rfc3966#section-3[RFC3966 `global-number-digits`]. RFC XML: `front/author/address/phone`." + declaration: ":phone:, :phone{_i}:" + + address: + tags: ["Address attributes"] + title: "Address" + description: | + Used to directly format postal addresses without regard + to the prior types. Multiple lines are given as separate lines, each ending with a space, then a plus symbol, then a backslash symbol (`" + \"`). + + + The `postal-line` attribute is mutually exclusive with the presence of `street`, + `city`, `region`, `country` and `code` attributes (which are not currently supported). + + + RFC XML: `front/author/address/postal/postalLine` + + + [source,asciidoc] + ---- + :address: Palace + \ + Camel Lot 1 + \ + UK + ----. + declaration: ":address:, :address{_i}:" + +#--- Processing instructions for xml2rfc ---# + artworkdelimiter: + tags: ["Processing instructions for xml2rfc"] + title: "Artwork delimiter" + description: "When producing `txt` or `nroff` files, use this string to delimit artwork." + + artworklines: + tags: ["Processing instructions for xml2rfc"] + title: "Artwork lines" + description: "When producing txt or nroff files, add this many blank lines around artwork." + + authorship: + tags: ["Processing instructions for xml2rfc"] + title: "Authorship" + description: "Render author information." + + autobreaks: + tags: ["Processing instructions for xml2rfc"] + title: "Autobreaks" + description: "Automatically force page breaks to avoid widows and orphans (not perfect)." + + background: + tags: ["Processing instructions for xml2rfc"] + title: "Background image" + description: "When producing a HTML file, use this image." + + colonspace: + tags: ["Processing instructions for xml2rfc"] + title: "Colon space" + description: 'Put two spaces instead of one after each colon ("`:`") in txt or nroff files.' + + comments: + tags: ["Processing instructions for xml2rfc"] + title: "Comments" + description: "Render `` information." + + docmapping: + tags: ["Processing instructions for xml2rfc"] + title: "Document mapping" + description: "Use hierarchical tags (e.g., `

`, `

`, etc.) for (sub)section titles." + + editing: + tags: ["Processing instructions for xml2rfc"] + title: "Editing" + description: "Insert editing marks for ease of discussing draft versions." + + emoticonic: + tags: ["Processing instructions for xml2rfc"] + title: "Emoticonic" + description: "Automatically replaces input sequences such as `|*text|` by, e.g., `text` in html output." + + footer: + tags: ["Processing instructions for xml2rfc"] + title: "Footer" + description: "Override the center footer string." + + header: + tags: ["Processing instructions for xml2rfc"] + title: "Header" + description: "Override the leftmost header string." + + inline: + tags: ["Processing instructions for xml2rfc"] + title: "Inline" + description: "If comments is "yes", then render comments inline; otherwise render them in an "Editorial Comments" section." + + iprnotified: + tags: ["Processing instructions for xml2rfc"] + title: "IPR notified" + description: "Include boilerplate from Section 10.4(d) of http://tools.ietf.org/html/rfc2026." + + linkmailto: + tags: ["Processing instructions for xml2rfc"] + title: "Generate mailto" + description: "Generate mailto: URL, as appropriate." + + linefile: + tags: ["Processing instructions for xml2rfc"] + title: "linefile" + description: "A string like "35:file.xml" or just "35" (file name then defaults to the containing file's real name or to the latest linefile specification that changed it) that will be used to override xml2rfc's reckoning of the current input position (right after this PI) for warning and error reporting purposes (line numbers are 1-based)." + + notedraftinprogress: + tags: ["Processing instructions for xml2rfc"] + title: "Note draft in progress" + description: 'Generates "(work in progress)", as appropriate.' + + private: + tags: ["Processing instructions for xml2rfc"] + title: "private" + description: "Produce a private memo rather than an RFC or Internet-Draft." + + refparent: + tags: ["Processing instructions for xml2rfc"] + title: "Ref parent" + description: "Title of the top-level section containing all references." + + rfcedstyle: + tags: ["Processing instructions for xml2rfc"] + title: "rfcedstyle" + description: | + Attempt to closely follow finer details from the latest observable RFC-Editor style so as to minimize the probability of being sent back corrections after submission. + + This directive is a kludge whose exact behavior is likely to change on a regular basis to match the current flavor of the month; presently, it will: + + * capitalize the adjective "`This`" in automatically generated headings, + * use the variant "`acknowledgement`" spelling instead of Merriam Webster's main "`acknowledgment`" dictionary entry, + * use the "`eMail`" spelling instead of Knuth's more modern "`email`" spelling, + * only put one blank line instead of two before top sections, + * omit "`Intellectual Property and Copyright Statements`" and "`Author's Address`" from the table of content, and + * not limit the indentation to a maximum tag length in `` sections. + + slides: + tags: ["Processing instructions for xml2rfc"] + title: "Slides" + description: "When producing a html file, produce multiple files for a slide show." + + strict: + tags: ["Processing instructions for xml2rfc"] + title: "Strict" + description: "Try to enforce the ID-nits conventions and DTD validity." + + subcompact: + tags: ["Processing instructions for xml2rfc"] + title: "Subcompact" + description: 'If compact is "yes", then you can make things a little less compact by setting this to "no" (the default value is the current value of the compact PI).' + + text-list-symbols: + tags: ["Processing instructions for xml2rfc"] + title: "Text list symbols" + description: 'Modify the list of symbols used (when generated text) for list type="symbols". For example, specifying "abcde" will cause "a" to be used for 1st level, "b" for the 2nd level, etc, cycling back to the first character "a" at the 6th level. Specifying "o*" will cause the characters "o" and "*" to be alternated for each successive level.' + + toc-include: + tags: ["Processing instructions for xml2rfc"] + title: "Generate table of contents" + description: "(`toc`) generate a table-of-contents." + + tocappendix: + tags: ["Processing instructions for xml2rfc"] + title: "ToC appendix" + description: "Control whether the word "Appendix" appears in the table-of-content." + + toc-depth: + tags: ["Processing instructions for xml2rfc"] + title: "ToC depth" + description: 'If `:toc-include:` is "yes", then this determines the depth of the table-of-contents.' + + tocindent: + tags: ["Processing instructions for xml2rfc"] + title: "ToC indent" + description: 'If `:toc-include:` is "yes", then setting this to "yes" will indent subsections in the table-of-contents.' + + tocnarrow: + tags: ["Processing instructions for xml2rfc"] + title: "ToC narrow" + description: "Affects horizontal spacing in the table-of-content." + + tocompact: + tags: ["Processing instructions for xml2rfc"] + title: "ToC compact" + description: 'If `:toc-include:` is "yes", then setting this to "no" will make it a little less compact.' + + topblock: + tags: ["Processing instructions for xml2rfc"] + title: "topblock" + description: "Put the famous header block on the first page." + + useobject: + tags: ["Processing instructions for xml2rfc"] + title: "useobject" + description: "When producing a html file, use the html element with inner replacement content instead of the html element, when a source xml element includes an src attribute." diff --git a/reference_docs/YAML_models/iso_document_attributes.yaml b/reference_docs/YAML_models/iso_document_attributes.yaml new file mode 100644 index 00000000..c459087a --- /dev/null +++ b/reference_docs/YAML_models/iso_document_attributes.yaml @@ -0,0 +1,215 @@ +version: v3.4.5 #Verify versions + +inherits_from: + # Also may be referred to as “parent flavor” + flavor: standoc + version: v1.x.x + +document_attributes: +#--- Document info ---# + tc-docnumber: + tags: ["Document info"] + title: "Technical Committee Document Number" + description: "Document number assigned by the Technical committee." + required: "don't know" + + partnumber: + tags: ["Document info"] + title: "Part Number" + description: "ISO document part number. This can be “part-subpart” if this is an ISO/IEC or IEC document." + required: "don't know" + + doctype: + tags: ["Document info"] + title: "Document Type" + description: "Assign one of the predefined document types to your document." + required: true + value_spec: "enum: international-standard, technical-specification, technical-report, publicly-available-specification, international-workshop-agreement, guide, technical-corrigendum, amendment" + value_default: international-standard + + updates-document-type: + tags: ["Document info"] + title: "Update document type" + description: "Indicates the type of the document that is being updated by an Amendment or Technical Corrigendum. (Only valid when `doctype` is set to `amendment` or `technical-corrigendum`.)" + required: "don't know" + added_in_version: v1.3.25 + + docsubtype: + tags: ["Document info"] + title: "Document subtype" + description: | + A subclass of doctype for which special processing rules apply: + - vocabulary: The "vocabulary" document type is defined in the ISO House Rules and title requirements defined in the ISO/IEC Directives, Part 2, 2018, 11.5.2. The initial clause of the terms section, “For the purposes of this document, the following terms and definitions apply”, is deleted; terminological entries are permitted outside of Clause 3. + added_in_version: v1.8.2 + more_information: "See https://www.iso.org/ISO-house-style.html[ISO house style]" + + docstage: + tags: ["Document info"] + title: "Document Stage" + description: | + Stage code for the document status (see International harmonized stage codes). Synonym of `:status:`. + ISO authors usually create Metanorma documents at stages 00 through 40 (PWI 00., AWI, NP, WD, CD, DIS). Documents at the final stages, 50 and 60 (FDIS, PRF, IS), are created by ISO Editorial Program Managers at ISO/CS (aka ISO EPMs, ISO Editors). Authors using Metanorma are not expected to edit documents at those stages, and are not necessary in a normal submission process. These stages, however, can be used for mirroring and tracking of final stage and published standards, which many authors do. + required: true + more_information: "See https://www.iso.org/stage-codes.html[ISO stage codes]" + + docsubstage: + tags: ["Document info"] + title: "Document Sub-stage" + description: "Substage code for the document status (see International harmonized stage codes). If this is left out, a substage of “00” is assumed, with the exception of stage “60” (published), where a substage of “60” is assumed. (“60.00” is the final proof “PRF stage”, “60.60” the published document “published”.)" + required: "don't know" + more_information: "See https://www.iso.org/stage-codes.html[ISO stage codes]" + + horizontal: + tags: ["Document info"] + title: "Horizontal" + description: "Document is a horizontal standard." + value_spec: boolean + added_in_version: v1.5.13 + +#--- Title ---# + title-intro-en: + tags: ["Title"] + title: "Introductory Document Title" + description: "Introductory component of the English title of the document." + + title-intro-fr: + tags: ["Title"] + title: "Introductory Document Title" + description: "Introductory component of the French title of the document." + + title-main-en: + tags: ["Title"] + title: "Main Document Title" + description: "Main component of the English title of the document." + required: true + + title-main-fr: + tags: ["Title"] + title: "Main Document Title" + description: "Main component of the French title of the document." + required: true + + title-part-en: + tags: ["Title"] + title: "Document Part Title" + description: "English title of the document part." + + title-part-fr: + tags: ["Title"] + title: "Document Part Title" + description: "French title of the document part." + + title-amendment-en: + tags: ["Title"] + title: "Title Ammendment in English" + description: "English title of the amendment. (Only when `doctype` is set to `amendment` or `technical-corrigendum`.)" + added_in_version: v1.3.25 + + title-amendment-fr: + tags: ["Title"] + title: "Title Ammendment in French" + description: "French title of the amendment. (Only when `doctype` is set to `amendment` or `technical-corrigendum`.)" + added_in_version: v1.3.25 + + amendment-number: + tags: ["Title"] + title: "Amendment Number" + description: "Number of the amendment. Use only when `doctype` is set to `amendment`." + value_spec: number + added_in_version: v1.3.25 + + corrigendum-number: + tags: ["Title"] + title: "Corrigendum Number" + description: "Number of the technical corrigendum. Use only when `doctype` is set to `technical-corrigendum`." + value_spec: number + added_in_version: v1.3.25 + + +#--- Author info ---# + secretariat: + tags: ["Author info"] + title: "Secretariat" + description: "National body acting as the secretariat for the document in the drafting stage." + required: "don't know" + + technical-committee-number: + tags: ["Author info"] + title: "Technical Committee Number" + description: "Number of the relevant ISO technical committee." + required: "don't know" + declaration: ":technical-committee-number:, :technical-committee-number{_i}:" + value_spec: number + example: | + In case of having more than one Technical Committee Number, multiple groups + can be encoded by suffixing `_i` to the attribute where `i` is a sequential number after 1. + Ex. ":technical-committee-number_2:", ":technical-committee-number_3:", ":technical-committee-number_i:" + + technical-committee-type: + tags: ["Author info"] + title: "Technical Committee Type" + description: "Type of the relevant technical committee." + required: "don't know" + value_spec: "enum: TC, PC, JTC, JPC" + value_default: "TC" + + technical-committee: + tags: ["Author info"] + title: "Technical Committee" + description: "Name of the relevant ISO technical committee." + required: true + declaration: ":technical-committee:, :technical-committee{_i}:" + example: | + In case of having more than one Technical Committee, multiple groups + can be encoded by suffixing `_i` to the attribute where `i` is a sequential number after 1. + Ex. ":technical-committee_2:", ":technical-committee_3:", ":technical-committee_i:" + + subcommittee-number: + tags: ["Author info"] + title: "Subcommittee Number" + description: "Number of the relevant ISO subcommittee." + required: "don't know" + declaration: ":subcommittee-number:, :subcommittee-number{_i}:" + value_spec: number + example: | + In case of having more than one Subcommittee Number, multiple groups + can be encoded by suffixing `_i` to the attribute where `i` is a sequential number after 1. + Ex. ":subcommittee-number_2:", ":subcommittee-number_3:", ":subcommittee-number_i:" + + subcommittee-type: + tags: ["Author info"] + title: "Subcommittee Type" + description: "Type of the relevant ISO subcommittee. Typical values: SC, JSC." + required: "don't know" + value_default: "SC" + + subcommittee: + tags: ["Author info"] + title: "Subcommittee" + description: "Name of the relevant ISO subcommittee." + required: "don't know" + declaration: ":subcommittee:, :subcommittee{_i}:" + example: | + In case of having more than one Subcommittee, multiple groups can be encoded by suffixing `_i` to the attribute where `i` is a sequential number after 1. + + Ex. ":subcommittee_2:", ":subcommittee_3:", ":subcommittee_i:" + + workgroup-number: + tags: ["Author info"] + title: "Workgroup Number" + description: "Number of the relevant ISO working group." + required: "don't know" + value_spec: number + + workgroup-type: + tags: ["Author info"] + title: "Workgroup Number" + description: "Type of the relevant ISO working group." + required: "don't know" + value_default: "WG" + example: "`JWG`, `JAG`, `AG` (advisory group), `AHG`, `SWG`, `SG`, `MA` (maintenance agency), `CORG`, `JCG`, `CAG`" + + workgroup: + tags: ["Author info"] + title: "Workgroup" + description: "Type of the relevant ISO working group." + required: "don't know" diff --git a/reference_docs/YAML_models/ogc_document_attributes.yaml b/reference_docs/YAML_models/ogc_document_attributes.yaml new file mode 100644 index 00000000..bd5c2719 --- /dev/null +++ b/reference_docs/YAML_models/ogc_document_attributes.yaml @@ -0,0 +1,188 @@ +version: v3.4.5 #Verify versions + +inherits_from: + # Also may be referred to as “parent flavor” + flavor: standoc + version: v1.x.x + +document_attributes: +#--- Document info ---# + abbrev: + tags: ["Document info"] + title: "Standard abbreviation" + description: "Standard abbreviation of the document, used e.g. in URIs." + + doctype: + tags: ["Document info"] + title: "Document type" + description: | + Document type. Choices: + + + -- + * `standard`: Standard (requires a document subtype) + * `abstract-specification-topic`: Abstract Specification + * `best-practice`: Best Practice (requires a document subtype) + * `change-request-supporting-document`: Change Request Supporting Document + * `community-practice`: Community Practice + * `community-standard`: Community Standard + * `discussion-paper`: Discussion Paper + * `engineering-report`: Engineering Report + * `other`: Note, Primer, etc. + * `policy`: Policy, Name Type Specification + * `reference-model`: Reference Model + * `release-notes`: Release Notes + * `test-suite`: Test Suite + * `user-guide`: User Guide + * `white-paper`: White Paper + -- + required: true + value_spec: "enum: standard, abstract-specification-topic, best-practice, change-request-supporting-document, community-practice, community-standard, discussion-paper, engineering-report, other, policy, reference-model, release-notes, test-suite, user-guide, white-paper" + value_default: standard + + docsubtype: + tags: ["Document info"] + title: "Document subtype" + description: | + Document subtype. + Choices: + + + -- + * For `doctype` set to `standard`: + ** `implementation`: Implementation (_default_) + ** `conceptual-model`: Conceptual model + ** `conceptual-model-and-encoding`: Conceptual model and encoding + ** `conceptual-model-and-implementation`: Conceptual model and implementation + ** `encoding`: Encoding + ** `extension`: Extension + ** `profile`: Profile + ** `profile-with-extension`: Profile with extension + + * For `doctype` set to `best-practice`: + ** `general`: General (_default_) + ** `encoding`: Encoding + ** `extension`: Extension + ** `profile`: Profile + ** `profile-with-extension`: Profile with extension + -- + value_default: "implementation, general" + + status: + tags: ["Document info"] + title: "Status" + description: | + Document status/stage. Synonym: `:docstage:`. + Choices: + + + -- + * `swg-draft`: SWG Draft. This is the draft created after the TC approval and PC approval votes. + * `oab-review`: OAB Review. This is the intended draft for the "`OAB + OGC-NA Review`". + * `public-rfc`: Public RFC. This is the draft for the (30 days) public comment period. + * `tc-vote`: TC Vote. This is the intended draft for the TC adoption and PC adoption votes. + * `approved`: Published. This is the document intended to be published, after comments are handled with the TC chair (after `tc-vote`). `published` is allowed as a synonym of `approved` [added in https://github.com/metanorma/metanorma-ogc/releases/tag/v1.2.5]. + * `deprecated`: Deprecated. This document has been deprecated. + * `retired`: Retired. This document has been retired and no longer considered normative. + -- + required: "don't know" + value_spec: "enum: swg-draft, oab-review, public-rfc, tc-vote, approved, deprecated, retired" + + edition: + tags: ["Document info"] + title: "Edition" + description: "Version number of the document. Dot-delimited, consists of a major version number, a minor version number, and an optional patch version number; e.g. `2.3.1`: major version 2, minor version 3, patch version 1." + +#--- Author info ---# + committee: + tags: ["Author info"] + title: "Committee" + description: "Name of relevant committee producing the document." + required: true + value_spec: "enum: technical, planning, strategic-member-advisory" + + subcommittee-type: + tags: ["Author info"] + title: "Subcommittee type" + description: "Type of the relevant subcommittee producing the document." + + subcommittee-number: + tags: ["Author info"] + title: "Subcommittee number" + description: "Number of the relevant subcommittee producing the document." + value_spec: number + + workingGroup: + tags: ["Author info"] + title: "Working Group" + description: "Name of relevant working group producing the document." + required: true + + workgroup-type: + tags: ["Author info"] + title: "Workgroup Type" + description: "Type of the relevant workgroup producing the document." + + workgroup-number: + tags: ["Author info"] + title: "Workgroup number" + description: "Number of the relevant workgroup producing the document." + value_spec: number + + submitting-organizations: + tags: ["Author info"] + title: "Submitting organizations" + description: "Semicolon-delimited list of the submitting organizations for this document. The organization names themselves may contain commas." + example: "_University of Calgary, Canada; National Central University, Taiwan_" + + editor: + tags: ["Author info"] + title: "Editor" + description: "Same as `:fullname:` alongside `:role:` specified as `editor`." + example: | + [source,asciidoc] + ---- + :editor: Scott Henderson + :editor_2: Andy Timmons + ---- + + is the same as: + + [source,asciidoc] + ---- + :fullname: Scott Henderson + :role: editor + :fullname_2: Andy Timmons + :role_2: editor + ---- + +#--- URIs and IDs ---# + external-id: + tags: ["URIs and IDs"] + title: "External ID" + description: | + External identifier referring to this document. If not supplied, a default value is generated: `http://www.opengis.net/doc/{abbrevation of doctype}/{abbrev}/{version}`. + + If there is no version is provided, it will be omitted. If `:abbrev:` and `:doctype:` are not provided, the default value is not generated. + + referenceURLID: + tags: ["URIs and IDs"] + title: "Reference URL" + description: "Identifier embedded into a document type-specific external URL." + + previous-uri: + tags: ["URIs and IDs"] + title: "Previous URI" + description: "URI of previous version of the document." + + docnumber: + tags: ["URIs and IDs"] + title: "Document number" + description: | + The document number assigned to the OGC document (without the "`OGC`" prefix). + + The number is formulated according to the following rules: + + + * The final two digits of the year are used at the start of the number (`YY`). + * A three digit number is assigned sequentially for each document in the year (`NNN`). + * The first edition of a document has the document number `YY-NNN`; for example, `00-027` is OGC document 027 first published in 2000. + * Minor editorial changes and corrigenda do not result in a change to the document number + * The `YY-NNN` identifier for a document (the document number root) is maintained if the document undergoes content changes (revisions). These revisions are numbered sequentially, and are indicated with `r` followed by the revision number. So `05-020r27` is revision 27 of OGC document 020 first published in 2005. (Revision 27 may appear years later than 2005.) + * A new major version of a document receives a new document number, including likely a new year. diff --git a/reference_docs/YAML_models/standoc_document_attributes.yaml b/reference_docs/YAML_models/standoc_document_attributes.yaml new file mode 100644 index 00000000..9494f139 --- /dev/null +++ b/reference_docs/YAML_models/standoc_document_attributes.yaml @@ -0,0 +1,728 @@ +# How to use this template: +# Within the document_attributes section, there are several key value pairs to model a reference entry. +# A complete reference entry looks like this: +# nameOfTheAttribute: # Unique across document attributes for a flavor +# tags: [] # A list of strings; Include flavor and type of attribute, e.g. "Author info" +# title: "name of the attribute" +# description: "Can contain inline and block AsciiDoc formatting." +# required: true #Describes if the attribute is required to generate a well-formed doc or optional. Takes a boolean. +# declaration: ":attribute:" #How the attribute is invoked +# value_spec: "Comma-delimited list of classification tokens, expressed as `type:value` pairs. The `type:` prefix is optional, where omitted `default:` prefix is auto-supplied" +# value_default: null #OPTIONAL A string showing literal value for this attribute, without quotes. If the attribute doesn't take a values, this stays empty. +# added_in_version: v1.9.1 # Could be auto-inferred, however the renderer might run into trouble, see https://github.com/metanorma/metanorma.org/wiki/Flavor-reference-structure-specification +# example: >- ... #OPTIONAL Should be pure AsciiDoc. Will be rendered as is inside an example block. +# more_information: "string" #OPTIONAL Use to provide related links, such as a blog article that discusses background info, if applicable + +version: v1.x.x #@opoudjis Check versions throughout this doc. Huuuge thanks! +flavor: standoc + +document_attributes: +#--- Build and validation ---# + nodoc: + tags: ["Build and validation"] + title: "No document generation" + description: "Instructs Metanorma to only generate XML output. Word and HTML output will not be generated." + + novalid: + tags: ["Build and validation"] + title: "No document validation" + description: "Suppress document validation." + + #--- Bibliographic lookup ---# + no-isobib: + tags: ["Bibliographic lookup"] + title: "No reference lookup" + description: | + Disable automatic reference lookup. + If set, do not use the `relaton` or `iev` gem functionality to look up ISO and IEV references online, nor the cache of `relaton` and `iev` searches. + more_information: "For bibliographic lookup, see link:https://www.metanorma.org/author/topics/building/reference-lookup[automatic reference lookup]." + +#--- Please include all Bibliographic lookup references from https://www.metanorma.org/author/topics/building/reference-lookup/ ---# + + + #--- Caches ---# + #--- Is there some reference information hidden in https://www.metanorma.org/author/topics/building/reference-lookup/#lookup-result-caching ? ---# + + no-isobib-cache: + tags: ["Caches"] + title: "No isobib cache" + description: "If set, use the relaton and iev gem functionality to look up ISO and IEV references online, but do not use the cache of relaton and iev searches." + + local-cache: + tags: ["Caches"] + title: "Local cache" + description: "Use the local relaton and iev search caches to override the global relaton and iev search caches. If a directory name is given for the attribute, that name overrides relaton as the cache name." + + local-cache-only: + tags: ["Caches"] + title: "Local cache only" + description: | + Use the local relaton and iev search caches to the exclusion of the global + `relaton` and `iev` search caches. + If a directory name is given for the attribute, that name overrides `relaton` as the cache name. + + flush-caches: + tags: ["Caches"] + title: "Flush caches" + description: "If set, delete and reinitialise the cache of `https://www.relaton.com/[relaton]` searches." + + #--- Math ---# + #--- Please include all references from https://www.metanorma.org/author/topics/document-format/text/#mathematical-expressions ---# + stem: + tags: ["Math"] + title: "Mathematical Markup Language" + description: "This attribute is required if you have any AsciiMath, MathML, or LaTeX included in the document; otherwise they will not be detected. If you want the STEM expressions in your document to be interpreted as LaTeX by default, use `:stem: latexmath`." + value_spec: "enum: latexmath, asciimath" + more_information: "Read more about working with link:/author/topics/document-format/text/#mathematical-expressions[mathematical expressions]. Additional information see link:/author/ref/asciimath/[AsciiMath reference]" + + + #--- Languages and localization ---# + #--- Please include all references from https://www.metanorma.org/author/topics/languages/ ---# + i18nyaml: + tags: ["Languages and localization"] + title: "YAML language template" + 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]. + + language: + tags: ["Languages and localization"] + title: "Language" + description: "Two-letter code (ISO 639-1) of the language the document is written in. Defaults to `en`." + value_default: en + + script: + tags: ["Languages and localization"] + title: "Script" + description: "Script of the document (ISO 15924). Defaults to `Latn`. Must be supplied as `Hans` for Simplified Chinese." + value_spec: "enum: Arab, Aran, Cyrl, Deva, Grek, Hans, Kore, Hebr, Jpan, Latn" + value_default: Latn + + 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]." + added_in_version: v1.3.15 + + #--- Document info ---# + publisher: + tags: ["Document info"] + title: "Publisher" + description: "Standards agency publishing the standard; can be multiple (semicolon-delimited: processed via CSV, recognising quote marks)." + value_spec: comma-list + added_in_version: v1.5.1 + + + copyright-holder: + tags: ["Document info"] + title: "Copyright holder" + description: "Copyright holder, if distinct from the publisher; can be multiple (semicolon-delimited: processed via CSV, recognising quote marks)." + value_spec: comma-list + added_in_version: v1.5.1 + + docnumber: + tags: ["Document info"] + title: "Document number" + description: "Numeric component of the document identifier. The full identifier is formed by prefixing and suffixing this element with other strings derived from metadata." + + edition: + tags: ["Document info"] + title: "Edition" + description: "Document edition." + + revdate: + tags: ["Document info"] + title: "Revision date" + description: "Date the document was last updated." + + library-ics: + tags: ["Document info"] + title: "Library ICS" + description: "ICS (International Categorization for Standards) number for the standard. There may be more than one ICS for a document; if so, they should be comma-delimited. Depending on the Metanorma flavor, the ICS identifier is added to the document metadata, but may not be visible in the resulting document.)" + + isbn: + tags: ["Document info"] + title: "ISBN-13 number" + description: "ISBN-13 number of the document." + added_in_version: v1.6.2 + + isbn10: + tags: ["Document info"] + title: "ISBN-10 number" + description: "ISBN-10 number of the document." + added_in_version: v1.6.2 + + title: + tags: ["Document info"] + title: "Title of the document" + description: "Title of the document. If not supplied, the built-in AsciiDoc title (first line of document header) is used instead." + + title-XX: + tags: ["Document info"] + title: "Title of document in certain language" + description: "Title of the document in the language `XX` (where “XX” is a ISO 639-1 code; for example, `:title-en:`, `:title-fr`:)." + declaration: ":title-en:, :title-fr:" + + doctype: + tags: ["Document info"] + title: "Document type" + description: 'The document type; e.g. "standard", "guide", "report".' + + docsubtype: + tags: ["Document info"] + title: "Document subtype" + description: "Document subtype; by default, used to provide an ad hoc, user defined document class, unless provided for explicitly in the flavour, as in OGC." + + status: + tags: ["Document info"] + title: "Document status" + description: 'Status of the document; e.g. "draft", "published". Synonym: `:docstage:`.' + + docsubstage: + tags: ["Document info"] + title: "Document substage" + description: "Substage code for the document status, where applicable." + + iteration: + tags: ["Document info"] + title: "Iteration" + description: "Iteration of a stage, in case there have been multiple drafts (e.g. `2` on a `CD`: this is the second iteration through the `CD` stage)." + + keywords: + tags: ["Document info"] + title: "Keywords" + description: "Comma-delimited list of keywords associated with the document." + value_spec: comma-list + + classification: + tags: ["Document info"] + title: "Classification" + description: 'Comma-delimited list of classification tokens, expressed as `type:value` pairs, set by user; if no prefix is given to a value, "default" is supplied as the type.' + value_spec: comma-list + + draft: + tags: ["Document info"] + title: "Document draft" + description: "Document draft. Used in addition to document stage. The value must provide the exact draft iteration in _X.Y_ format (major version number and minor version number separated by a dot). If present, link:/author/topics/document-format/reviewer-notes[reviewer notes] will be rendered (otherwise those are suppressed)." + + #--- URIs ---# + uri: + tags: ["URIs"] + title: "URI" + description: "URI to which this standard is published." + + xml-uri: + tags: ["URIs"] + title: "XML URI" + description: "URI to which the (Metanorma) XML representation of this standard is published." + + html-uri: + tags: ["URIs"] + title: "HTML URI" + description: "URI to which the HTML representation of this standard is published." + + pdf-uri: + tags: ["URIs"] + title: "PDF URI" + description: "URI to which the PDF representation of this standard is published." + + doc-uri: + tags: ["URIs"] + title: "DOC URI" + description: "URI to which the DOC representation of this standard is published." + + relaton-uri: + tags: ["URIs"] + title: "Relaton URI" + description: "URI to which the Relaton XML representation of this standard is published." + + + #--- Timestamps ---# + copyright-year: + tags: ["Timestamps"] + title: "Copyright year" + description: "Year in which the copyright for the document was issued." + + issued-date: + tags: ["Timestamps"] + title: "Issued date" + description: "Date on which the standard was issued (authorised for publication by the issuing authority)." + + published-date: + tags: ["Timestamps"] + title: "Published date" + description: "Date on which the standard was published (distributed by the publisher)." + + implemented-date: + tags: ["Timestamps"] + title: "Implemented date" + description: "Date on which the standard became active." + + created-date: + tags: ["Timestamps"] + title: "created date" + description: "Date on which the first version of the standard was created." + + updated-date: + tags: ["Timestamps"] + title: "Updated date" + description: "Date on which the current version of the standard was updated." + + obsoleted-date: + tags: ["Timestamps"] + title: "Obsoleted date" + description: "Date on which the standard was obsoleted/revoked." + + confirmed-date: + tags: ["Timestamps"] + title: "Confirmed date" + description: "Date on which the standard was reviewed and approved by the issuing authority." + + unchanged-date: + tags: ["Timestamps"] + title: "Unchanged date" + description: "Date on which the standard was last renewed without any changes in content." + + circulated-date: + tags: ["Timestamps"] + title: "Circulated date" + description: "Date on which the unpublished standard was last circulated officially as a preprint. For standards, this is associated with the latest transition to a formally defined preparation stage, such as Working Draft or Committee Draft." + + accessed-date: + tags: ["Timestamps"] + title: "Accessed date" + description: "Date on which the standard was last accessed by the compiler of the bibliography; e.g. for a cited online resource, the date on which the document author viewed the resource." + + date: + tags: ["Timestamps"] + title: "Date" + description: "An arbitrary date in the production of the standard. Content of the attribute should be a token, giving the type of date, then space, then the date itself. Multiple dates can be added as `:date_2:`, `:date_3:`, etc." + + vote-started-date: + tags: ["Timestamps"] + title: "Vote started date" + description: "Date on which the voting process starts for this document." + + vote-ended-date: + tags: ["Timestamps"] + title: "Vote ended date" + description: "Date on which the voting process ends for this document." + + announced-date: + tags: ["Timestamps"] + title: "Announced date" + description: "Date on which the document was announced as forthcoming." + added_in_version: v1.9.3 + + #--- Author info ---# + technical-committee: + tags: ["Author info"] + title: "Technical committee" + description: "Name of the relevant technical committee." + + fullname: + tags: ["Author info"] + title: "Fullname" + description: | + Full name of a person who is a contributor to the document. A second person is indicated by using a numeric suffix: `:fullname:`, `:fullname_2:`, `fullname_3:`, &c. The same convention applies to all the following attributes. + + NOTE: Not all standards display the `fullname` and other personal name attributes. + declaration: ":fullname:, :fullname_{i}:" + + surname: + tags: ["Author info"] + title: "Surname" + description: "Surname of a person who is a contributor to the document." + declaration: ":surname:, :surname_{i}:" + + givenname: + tags: ["Author info"] + title: "Given name" + description: "Given name(s) of a person who is a contributor to the document." + declaration: ":givenname:, :givenname_{i}:" + + initials: + tags: ["Author info"] + title: "Initials" + description: "Initials(s) of a person who is a contributor to the document." + declaration: ":initials:, :initials_{i}:" + + role: + tags: ["Author info"] + title: "Role" + description: | + Role of a person who is a contributor to the document. + By default, they are coded as an `editor`; they can also be represented as an `author`. + declaration: ":role:, :role_{i}:" + + affiliation: + tags: ["Author info"] + title: "Organization" + description: "Organization that a person who is a contributor to the document is affiliated with." + declaration: ":affiliation:, :affiliation{_i}:" + + affiliation_abbrev: + tags: ["Author info"] + title: "Abbreviation of organization" + description: "Abbreviation of the organization that a person who is a contributor to the document is affiliated with." + declaration: ":affiliation_abbrev:, :affiliation_abbrev{_i}:" + added_in_version: v1.3.12 + + affiliation_subdiv: + tags: ["Author info"] + title: "Subdivision of the organization" + description: | + Subdivision of the organization that a contributor to the document is affiliated with. + Can be multiple (semicolon-delimited: processed via CSV, recognising quote marks). + declaration: ":affiliation_subdiv:, :affiliation_subdiv{_i}:" + added_in_version: v1.7.0 + + address: + tags: ["Author info"] + title: "Address" + description: "Organizational address of a person who is a contributor to the document. Mutually exclusive with street/city/region/country/postcode." + declaration: ":address:, :address{_i}:" + + street: + tags: ["Author info"] + title: "Street component" + description: "Street component of the organization address of a person who is a contributor to the document." + declaration: ":street:, :street{_i}:" + added_in_version: v1.9.4 + + city: + tags: ["Author info"] + title: "City component" + description: "City component of the organization address of a person who is a contributor to the document." + declaration: ":city:, :city{_i}:" + added_in_version: v1.9.4 + + region: + tags: ["Author info"] + title: "Region component" + description: "Region component of the organization address of a person who is a contributor to the document." + declaration: ":region:, :region{_i}:" + added_in_version: v1.9.4 + + country: + tags: ["Author info"] + title: "Country" + description: "Country component of the organization address of a person who is a contributor to the document." + declaration: ":country:, :country{_i}:" + added_in_version: v1.9.4 + + postcode: + tags: ["Author info"] + title: "postcode" + description: "Postcode component of the organization address of a person who is a contributor to the document." + declaration: ":postcode:, :postcode{_i}:" + added_in_version: v1.9.4 + + contributor-uri: + tags: ["Author info"] + title: "Contributor URI" + description: "URI of a person who is a contributor to the document." + declaration: ":pcontributor-uri:, :contributor-uri{_i}:" + + + email: + tags: ["Author info"] + title: "Email address" + description: "Email of a person who is a contributor to the document." + declaration: ":email:, :email{_i}:" + + phone: + tags: ["Author info"] + title: "Phone number" + description: "Phone number of a person who is a contributor to the document." + declaration: ":phone:, :phone{_i}:" + + fax: + tags: ["Author info"] + title: "Fax number" + description: "Fax number of a person who is a contributor to the document." + declaration: ":fax:, :fax{_i}:" + + subdivision: + tags: ["Author info"] + title: "Subdivision of the organization" + description: "Subdivision of the organization that is responsible for this document." + added_in_version: v1.6.1 + + subdivision-abbr: + tags: ["Author info"] + title: "Subdivision abbreviation of the organization" + description: "Abbreviation of the subdivision of the organization that is responsible for this document." + added_in_version: v1.6.1 + + pub-address: + tags: ["Author info"] + title: "Address of the organization" + description: | + Address of the organization responsible for this document, if it overrides + the default. + + + [NOTE] + -- + Each line in a multi-line address must end with `+ \`, e.g. + + [source,adoc] + ---- + :pub-address: 1 Infinity Loop + \ + California + \ + United States of America + ---- + -- + added_in_version: v1.6.1 + + pub-phone: + tags: ["Author info"] + title: "Phone number of the organization" + description: "If set, it overrides the default phone number of the organization responsible for this document." + added_in_version: v1.6.1 + + pub-fax: + tags: ["Author info"] + title: "Fax number of the organization" + description: "If set, it overrides the default fax number of the organization responsible for this document." + added_in_version: v1.6.1 + + pub-email: + tags: ["Author info"] + title: "Email of the organization" + description: "If set, it overrides the default email of the organization responsible for this document." + added_in_version: v1.6.1 + + pub-uri: + tags: ["Author info"] + title: "URI of the organization" + description: "If set, it overrides the default URI of the organization responsible for this document." + added_in_version: v1.6.1 + + + #--- Visual appearance ---# + body-font: + tags: ["Visual appearance"] + title: "Body font" + description: "Font for body text; will be inserted into CSS, overriding the default set for the particular Metanorma flavour." + + header-font: + tags: ["Visual appearance"] + title: "Header font" + description: "Font for headers; will be inserted into CSS, overriding the default set for the particular Metanorma flavour." + + monospace-font: + tags: ["Visual appearance"] + title: "Monospace font" + description: "Font for monospace; will be inserted into CSS, overriding the default set for the particular Metanorma flavour." + + htmlstylesheet: + tags: ["Visual appearance"] + title: "HTML stylesheet" + description: "SCSS stylesheet to use for HTML output. Defaults to built-in template for the particular Metanorma flavour. Overriding is not recommended." + + htmlstylesheet-override: + tags: ["Visual appearance"] + title: "HTMLstylesheet override" + description: "CSS stylesheet to use for HTML output. Is inserted after any built in stylesheet for the particular Metanorma flavour, and can be used to override it." + added_in_version: v1.8.7 + + htmlcoverpage: + tags: ["Visual appearance"] + title: "HTML cover page" + description: | + HTML template for cover page. + + Defaults to built-in template for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + htmlintropage: + tags: ["Visual appearance"] + title: "HTML intro page" + description: | + HTML template for introductory section. + + Defaults to built-in template for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + scripts: + tags: ["Visual appearance"] + title: "Scripts" + description: | + JavaScript scripts for HTML output. + + Defaults to built-in scripts for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + scripts-override: + tags: ["Visual appearance"] + title: "scripts override" + description: "JavaScript scripts for HTML output. Inserted after any built-in scripts for the particular Metanorma flavour, and can be used to override them." + added_in_version: v1.9.4 + + scripts-pdf: + tags: ["Visual appearance"] + title: "scripts pdf" + description: | + JavaScript scripts for HTML to PDF output. + + Defaults to built-in scripts for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + wordstylesheet: + tags: ["Visual appearance"] + title: "Word stylesheet" + description: | + Primary SCSS stylesheet to use for Word output. + + Defaults to built-in template for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + standardstylesheet: + tags: ["Visual appearance"] + title: "Standard stylesheet" + description: | + Secondary SCSS stylesheet use for Word output. + + Defaults to built-in template for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + htmlstylesheet-override: + tags: ["Visual appearance"] + title: "HTML stylesheet override" + description: "CSS stylesheet to use for Word output. Is inserted after any built in stylesheets for the particular Metanorma flavour, and can be used to override them." + + header: + tags: ["Visual appearance"] + title: "Word header" + description: | + Header and footer file for Word output. + + Defaults to built-in template the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + wordcoverpage: + tags: ["Visual appearance"] + title: "Word cover page" + description: | + Word template for cover page. + + Defaults to built-in template for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + wordintropage: + tags: ["Visual appearance"] + title: "Word introductory section" + description: | + Word template for introductory section. + + Defaults to built-in template for the particular Metanorma flavour. + + Overriding is not recommended. + value_default: built-in + + ulstyle: + tags: ["Visual appearance"] + title: "Unordered list style" + description: | + Word CSS selector for unordered lists in supplied stylesheets. + + Defaults to value for built-in stylesheet. + + Overriding is not recommended. + + olstyle: + tags: ["Visual appearance"] + title: "Ordered list style" + description: | + Word CSS selector for ordered lists in supplied stylesheets. + + Defaults to value for built-in stylesheet. + + Overriding is not recommended. + + data-uri-image: + tags: ["Visual appearance"] + title: "Data-URI image" + description: "Encode all images in HTML output as inline data-URIs. Defaults to true." + value_default: true + + smartquotes: + tags: ["Visual appearance"] + title: "Smartquotes" + description: | + Apply "`smartquotes`" and other autoformatting to the XML output and the downstream outputs. + + + ** Smart quotes are not applied to the following type of text: + *** text in sourcecode + *** text in pseudocode + *** text in monospace. + ** If this attribute is set to `false`, the AsciiDoc default is used to generate smart quotes: + `"` `"`, `"` `"`. + ** The rules for smart formatting follow the + https://github.com/pbhogan/sterile[sterile] gem, and are given in + https://github.com/pbhogan/sterile/blob/main/lib/sterile/data/smart_format_rules.rb[smart_format_rules.rb]. + value_default: true + + toclevels: + tags: ["Visual appearance"] + title: "Table of contents levels" + description: "Number of table of contents levels to render." + value_spec: number + value_default: 2 + + htmltoclevels: + tags: ["Visual appearance"] + title: "HTML table of contents levels" + description: "Number of table of contents levels to render in HTML/PDF output; used to override `:toclevels:`." + value_spec: number + value_default: 2 + + doctoclevels: + tags: ["Visual appearance"] + title: "DOC table of contents levels" + description: "Number of table of contents levels to render in Word (`.doc`) output; used to override `:toclevels:`." + value_spec: number + value_default: 2 + + imagesdir: + tags: ["Visual appearance"] + title: "Images directory" + description: "Directory in which images are located: all local image file locations are prefixed with this directory." + + break-up-urls-in-tables: + tags: ["Visual appearance"] + title: "Break up URLs in tables" + description: | + If present, long strings in table cells (longer than 30 characters) are broken up on rendering, to help tables fit within the page width. + + + -- + NOTE: Due to limitations of Microsoft Word tables with long string + wrapping, this functionality is only applied to Word output. + -- + added_in_version: v1.3.29 + + sectionsplit: + tags: ["Visual appearance"] + title: "Section split" + description: | + Treat the HTML output as a Metanorma collection, with one web page per clause and annex. + NOTE: HTML output only. + added_in_version: v1.9.0 + + sourcecode-markup-start: + tags: ["Visual appearance"] + title: "Sourcecode markup start" + description: "Initial delimiter for markup inserted in sourcecode." + added_in_version: v1.7.4 + + sourcecode-markup-end: + tags: ["Visual appearance"] + title: "Sourcecode markup end" + description: "Final delimiter for markup inserted in sourcecode." + added_in_version: v1.7.4 + + bare: + tags: ["Visual appearance"] + title: "Bare" + description: | + The document is rendered "`bare`", without the coverpage, boilerplate, or introductory text expected of a complete standards document. + + This is used to compile into HTML e.g. clauses as standalone documents, or document attachments. + added_in_version: v1.9.4 diff --git a/tutorials/exercises.adoc b/tutorials/exercises.adoc new file mode 100644 index 00000000..2e47e08b --- /dev/null +++ b/tutorials/exercises.adoc @@ -0,0 +1,275 @@ +tag::exercise-2-1[] +Now it's your turn. Fill the document with the following attributes: +[%interactive] +* [ ] Document title +* [ ] Your name +* [ ] Your organization using the `:publisher:` attribute +* [ ] Your organization's address +* [ ] The document class: `standoc` +* [ ] The document type: `document` +* [ ] The language +* [ ] The copyright year + +.Hint +[%collapsible] +==== +To declare an attribute, follow the syntax `:attribute: value`. + +For example: `:publisher: Ribose Inc.` +==== +end::exercise-2-1[] + +tag::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. +Add the following sections: + +[%interactive] +* [ ] Foreword on line 13 +* [ ] Introduction on line 21 +* [ ] Terms and definitions on line 27 +* [ ] Bibliography on line 60 + +end::exercise-2-2[] + +tag::exercise-2-3-1[] +Add lists to the prepopulated document. + +[%interactive] +* [ ] Add an ordered list in lines 17-24. +* [ ] Add an unordered list in lines 36-40. +* [ ] Add a definition list in lines 46-48. + +.Hint +[%collapsible] +==== +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`. + +To write a definition list, follow the syntax: +`term:: Definition` +==== +end::exercise-2-3-1[] + +tag::exercise-2-3-2[] +Create a term definition entry for the term "immature kernel": +[%interactive] +* [ ] Add an alternative term ("unripe kernel") +* [ ] Add a deprecated term ("raw kernel") +* [ ] Add a definition: kernel, whole or broken, which is unripe and/or underdeveloped. + +.Hint +[%collapsible] +====== +The structure for a term definition looks like this: +[source, AsciiDoc] +---- +=== Term +alt:[alternative term] +deprecated:[deprecated term] + +definition +---- +====== +end::exercise-2-3-2[] + + +tag::exercise-2-3-3[] +Let's compare rice against wheat in a table: +[%interactive] +* [ ] Create an empty three column table with seven rows. +* [ ] Add a table title: "Nutrient profile of rice vs. wheat" +* [ ] Let's make the first column a bit wider than the other two colums in the ratio 3:2:2 by using the `cols` attribute. +* [ ] Populate the table like this: + + +[cols="3,2,2"] +.Nutrient profile of rice vs. wheat +|=== +|Nutrient | Rice| Wheat +|Energy (kJ)| 1736 | 1574 +|Protein (g)| 8.1 | 14.5 +|Fat (g)| 0.8 | 1.8 +|Carbohydrates (g)| 91 | 82 +|Fiber (g) | 1.5 | 14 +|Sugar (g)|0.1 | 0.5 +|=== + + +.Hint +[%collapsible] +====== +The structure for a three column table looks like this: +[source, AsciiDoc] +---- +|=== +||| +||| +||| +|=== +---- +====== +end::exercise-2-3-3[] + +tag::exercise-2-3-4[] +Insert an image of a rice plant in line 17 by following the steps below: +[%interactive] +* [ ] Add an image macro. +* [ ] Populate the `image::` macro with this link: + +---- + https://upload.wikimedia.org/wikipedia/commons/2/27/Oryza_sativa_-_K%C3%B6hler%E2%80%93s_Medizinal-Pflanzen-232.jpg +---- +[%interactive] +* [ ] Add a picture title (Oryza sativa) +* [ ] Create a key with three entries + +---- +A:: Rice - A flowering specimen of the variety _melanoceras_ Alef. +B:: blossom panicle +C:: crop panicle +---- + +.Hint +[%collapsible] +==== +The syntax for images is: `image::URL[]`. + +Make sure to include the square brackets after the link. +==== +end::exercise-2-3-4[] + +tag::exercise-2-3-5[] +Turn the existing text into admonitions: +[%interactive] +* [ ] Turn the text in line 15 into an `IMPORTANT` admonition. +* [ ] Turn the text in lines 17-19 into a `WARNING` admonition. +* [ ] Turn the text in line 21 into a `NOTE` admonition. + +.Hint +[%collapsible] +====== +To create admonitions that span several lines, you need to declare a block. +[source, AsciiDoc] +---- +[NOTE] +==== +This is a long note. +It contains three lines. +Line three. +==== +---- +====== +end::exercise-2-3-5[] + +tag::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. + +[%interactive] +* [ ] Create a source block with the attribute `ruby` for the code in lines 14-29. +* [ ] Create a source block with the attribute `python` for the code in line 32 +* [ ] Create a source block with the attribute `java` for the code in lines 35-39. + +.Hint +[%collapsible] +====== +Source code blocks look like this: + +[source, Asciidoc] +---- +[source, language] +==== +Code +==== +---- +====== +end::exercise-2-3-6[] + +tag::exercise-2-4-1[] +Format the text using the following formatting: +[%interactive] +* [ ] Add underline formatting to "Earth institute" in line 18 +* [ ] Add bold formatting to "from Africa, for Africa" in line 20 +* [ ] Add italic formatting to _The New York times_ and _International Herald Tribune_ in line 21 +* [ ] Add smallcaps formatting to all instances of "NERICA" +* [ ] Add a footnote on line 22 explaining the term "perennial". Footnote text: A perennial plant lives more than two years. +end::exercise-2-4-1[] + +tag::exercise-2-4-2[] +Let's add some index entries to the text. +[%interactive] +* [ ] Add a visible index entry to "UN Millennium Development project" in line 17 +* [ ] Add an invisible three level index entry after NERICA in line 21: NERICA, economy, Green revolution +* [ ] Add an invisible two level index entry in line 22 after rice: rice, perennial +* [ ] Create a new index section at the bottom of the document + +.Hint +[%collapsible] +==== +Visible index terms: `\((Level 1 index term))` + +Hidden index terms: `(\((Level 1 index term, Level 2 index term, Level 3 index term)))` +==== +end::exercise-2-4-2[] + +tag::exercise-2-4-3[] +Let's add some references to the sample document. + +Internal references: +[%interactive] +* [ ] Create an anchor for the table called `table1` +* [ ] Reference the table in lines 30 and 36. + +Bibliographic references: +The text references some standards which don't have a matching entry in the bibliography section. Add the following references: +[%interactive] +* [ ] ISO712, ISO712:2009, _Cereals and cereal products — Determination of moisture content — Reference method_ +* [ ] ISO7301, ISO 7301:2011, _Rice -- Specification_ +* [ ] IEC61010-2, IEC 61010-2:1998, _Safety requirements for electric equipment for measurement, control, and laboratory use -- Part 2: Particular requirements for laboratory equipment for the heating of material_ + +.Hint +[%collapsible] +==== +Setting an anchor: `\[[anchor]]` + +Referencing an anchor: `\<>` +==== +end::exercise-2-4-3[] + +tag::exercise-3-1[] +The text contains some typos. Mark the errors using comments. +[%interactive] +* [ ] Line 16: weter +* [ ] Line 18: exseed +* [ ] Line 20: eyes +end::exercise-3-1[] + +tag::exercise-3-2[] +Enter the command `metanorma document.adoc` into the terminal and see what happens. +end::exercise-3-2[] + +tag::exercise-4[] +The following document doesn't compile because there are some errors. + +. Enter `metnanorma exercise-4.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. +. Once you solved the errors, run `metanorma exercise-4.adoc` again to see if the document compiles. + +.Hint Error 1 +[%collapsible] +==== +Lines 12 and 43: Both sections have the anchor `\[[prefatory-clause]]` assigned. +You can solve this error by renaming the anchors. +==== + +.Hint Error 2 +[%collapsible] +==== +Line 76: The file that should be included cannot be found. +Since the scope section already contains text, you can delete the reference. +==== + +.Hint Error 3 +[%collapsible] +==== +Line 420: The image attribute contains a whitespace after `image::`, so the path is invalid. Delete the whitespace. +==== +end::exercise-4[] diff --git a/tutorials/exercises_code/exercise-2-1.adoc b/tutorials/exercises_code/exercise-2-1.adoc new file mode 100644 index 00000000..b19f2e6d --- /dev/null +++ b/tutorials/exercises_code/exercise-2-1.adoc @@ -0,0 +1,11 @@ +// Write the attributes here + + + + + + + + +//Content starts here +Lorem ipsum dolor sit amet. \ No newline at end of file diff --git a/tutorials/exercises_code/exercise-2-2.adoc b/tutorials/exercises_code/exercise-2-2.adoc new file mode 100644 index 00000000..f5dca23c --- /dev/null +++ b/tutorials/exercises_code/exercise-2-2.adoc @@ -0,0 +1,68 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +//Enter foreword section here + +The procedures used to develop this document and those intended for its further maintenance are described in the ISO/IEC Directives, Part 1. In particular the different approval criteria needed for the different types of ISO documents should be noted. This document was drafted in accordance with the editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives). + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights. Details of any patent rights identified during the development of the document will be in the Introduction and/or on the ISO list of patent declarations received (see www.iso.org/patents). + +Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement. + +//Enter introduction section here + +This document was developed in response to worldwide demand for minimum specifications for rice traded internationally, since most commercial bulks of grain, which have not been screened or aspirated, contain a proportion of other grains, weed seeds, chaff, straw, stones, sand, etc. The vegetable materials can have physical and biological properties which differ from those of the main constituent and can therefore affect the storage behaviour. + +... + +//Enter terms and definitions section here + +== Terms and definitions + +=== paddy +alt:[paddy rice] +alt:[rough rice] + +rice retaining its husk after threshing + +=== husked rice +deprecated:[cargo rice] + +term:[paddy] from which the husk only has been removed + + +=== milled rice +alt:[white rice] + +term:[husked rice] from which almost all of the bran and embryo have been removed by milling + +== Specifications + +=== General, organoleptic and health characteristics + +Kernels of rice, whether parboiled, husked or milled, and whether whole or broken, shall be sound, clean and free from foreign odours or odour which indicates deterioration. + +The levels of additives and pesticide residues and other contaminants shall not exceed the maximum limits permitted in the country of destination. + +The presence of living insects which are visible to the naked eye is not permitted. This should be determined before separating the bulk sample into test samples. + +... + + +//Enter bibliography section here + +== Bibliography + +* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_ + +* [[[ISO5725-1,ISO 5725-1]]], _Accuracy (trueness and precision) of measurement methods and results -- Part 1: General principles and definitions_ + +* [[[ISO5725-2,ISO 5725-2]]], _Accuracy (trueness and precision) of measurement methods and results -- Part 2: Basic method for the determination of repeatability and reproducibility of a standard measurement method_ \ No newline at end of file diff --git a/tutorials/exercises_code/exercise-2-3-1.adoc b/tutorials/exercises_code/exercise-2-3-1.adoc new file mode 100644 index 00000000..7fded598 --- /dev/null +++ b/tutorials/exercises_code/exercise-2-3-1.adoc @@ -0,0 +1,49 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +... +== Test report + +For each test method, the test report shall specify the following: +// Turn into ordered list +all information necessary for the complete identification of the sample; +a reference to this document (i.e. ISO {docnumber}-{partnumber}); +the sampling method used; +the test method used; +the test result(s) obtained or, if the repeatability has been checked, the final quoted result obtained; +all operating details not specified in this document, or regarded as optional, together with details of any incidents which may have influenced the test result(s); +any unusual features (anomalies) observed during the test; +the date of the test. + +== Terms + +=== extraneous matter +alt:[EM] +domain:[rice] + +organic and inorganic components other than whole or broken kernels + +[example] +==== +Foreign seeds +husks +bran +sand +dust +==== + +== Definitions + +Precision is a description of random errors, a measure of statistical variability. +Accuracy is a description of systematic errors, a measure of statistical bias; low accuracy causes a difference between a result and a "true" value. +Volumetric water content θ is defined as the ratio between volume of water and the volume of the total mass. + + diff --git a/tutorials/exercises_code/exercise-2-3-2.adoc b/tutorials/exercises_code/exercise-2-3-2.adoc new file mode 100644 index 00000000..eb59af77 --- /dev/null +++ b/tutorials/exercises_code/exercise-2-3-2.adoc @@ -0,0 +1,15 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + + +... +== Terms and definitions +// Enter your new definition here \ No newline at end of file diff --git a/tutorials/exercises_code/exercise-2-3-3.adoc b/tutorials/exercises_code/exercise-2-3-3.adoc new file mode 100644 index 00000000..21ef8732 --- /dev/null +++ b/tutorials/exercises_code/exercise-2-3-3.adoc @@ -0,0 +1,17 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +== Introduction +... + +The nutritional differences between rice and wheat are shown in the table below. + +// Enter the table here. \ No newline at end of file diff --git a/tutorials/exercises_code/exercise-2-3-4.adoc b/tutorials/exercises_code/exercise-2-3-4.adoc new file mode 100644 index 00000000..f6b3261a --- /dev/null +++ b/tutorials/exercises_code/exercise-2-3-4.adoc @@ -0,0 +1,21 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + + +== Scope + +This document specifies minimum requirements and test methods for rice (_Oryza sativa L._). + +//Insert image here. + +It is applicable to husked rice, husked parboiled rice, milled rice and milled parboiled rice, suitable for human consumption, directly or after reconditioning. + +It is not applicable to cooked rice products. diff --git a/tutorials/exercises_code/exercise-2-3-5.adoc b/tutorials/exercises_code/exercise-2-3-5.adoc new file mode 100644 index 00000000..ec25950c --- /dev/null +++ b/tutorials/exercises_code/exercise-2-3-5.adoc @@ -0,0 +1,21 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + + +== Introduction + +The following admonitions apply to to the entire standard. + +Direct contact of iodine with skin can cause lesions so care should be taken in handling iodine. +Iodine vapour is very irritating to eyes and mucous membranes. +Wear personal protection equipment such as masks and glasses. + +Only use paddy or parboiled rice for the determination of husked rice yield. diff --git a/tutorials/exercises_code/exercise-2-3-6.adoc b/tutorials/exercises_code/exercise-2-3-6.adoc new file mode 100644 index 00000000..ee942322 --- /dev/null +++ b/tutorials/exercises_code/exercise-2-3-6.adoc @@ -0,0 +1,54 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + + +// Ruby code +.The Greeter class +[source,ruby] +-- +class Greeter + def initialize(world) + @world = world.capitalize + end + + def salute + puts "Hello #{@world}!" + end +end +-- + +.Create a new object +[source,ruby] +-- +g = Greeter.new("world") +-- + +.Output "Hello World!" +[source,ruby] +-- +g.salute +-- + +// Python code +[source,python] +-- +print('Hello, World!') +-- + +// Java code +[source,java] +-- +class HelloWorld { + public static void main(String[] args) { + System.out.println("Hello, World!"); + } +} +-- \ No newline at end of file diff --git a/tutorials/exercises_code/exercise-2-4-1.adoc b/tutorials/exercises_code/exercise-2-4-1.adoc new file mode 100644 index 00000000..a501db1b --- /dev/null +++ b/tutorials/exercises_code/exercise-2-4-1.adoc @@ -0,0 +1,25 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +== Introduction +=== Future potential of rice +// Excerpt from https://en.wikipedia.org/wiki/Rice#Biotechnology + + +As the UN Millennium Development project seeks to spread global economic development to Africa, the "Green Revolution" is cited as the model for economic development. +With the intent of replicating the successful Asian boom in agronomic productivity, groups like the Earth Institute are doing research on African agricultural systems, hoping to increase productivity. +An important way this can happen is the production of "New Rices for Africa" (NERICA). +These rices, selected to tolerate the low input and harsh growing conditions of African agriculture, are produced by the African Rice Center, and billed as technology "from Africa, for Africa". +The NERICA have appeared in The New York Times (October 10, 2007) and International Herald Tribune (October 9, 2007), trumpeted as miracle crops that will dramatically increase rice yield in Africa and enable an economic resurgence. +Ongoing research in China to develop perennial rice could result in enhanced sustainability and food security. + + + diff --git a/tutorials/exercises_code/exercise-2-4-2.adoc b/tutorials/exercises_code/exercise-2-4-2.adoc new file mode 100644 index 00000000..596d8f57 --- /dev/null +++ b/tutorials/exercises_code/exercise-2-4-2.adoc @@ -0,0 +1,24 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +== Introduction +=== Future potential of rice +// Excerpt from https://en.wikipedia.org/wiki/Rice#Biotechnology + + +As the UN Millennium Development project seeks to spread global economic development to Africa, the "Green Revolution" is cited as the model for economic development. +With the intent of replicating the successful Asian boom in agronomic productivity, groups like the Earth Institute are doing research on African agricultural systems, hoping to increase productivity. +An important way this can happen is the production of "New Rices for Africa" (NERICA). +These rices, selected to tolerate the low input and harsh growing conditions of African agriculture, are produced by the African Rice Center, and billed as technology "from Africa, for Africa". +The NERICA have appeared in The New York Times (October 10, 2007) and International Herald Tribune (October 9, 2007), trumpeted as miracle crops that will dramatically increase rice yield in Africa and enable an economic resurgence. +Ongoing research in China to develop perennial rice could result in enhanced sustainability and food security. + +// Add the index section here \ No newline at end of file diff --git a/tutorials/exercises_code/exercise-2-4-3.adoc b/tutorials/exercises_code/exercise-2-4-3.adoc new file mode 100644 index 00000000..cb480cf0 --- /dev/null +++ b/tutorials/exercises_code/exercise-2-4-3.adoc @@ -0,0 +1,84 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + + +== Specifications + +=== General, organoleptic and health characteristics + +Kernels of rice, whether parboiled, husked or milled, and whether whole or broken, shall be sound, clean and free from foreign odours or odour which indicates deterioration. + +The levels of additives and pesticide residues and other contaminants shall not exceed the maximum limits permitted in the country of destination. + +The presence of living insects which are visible to the naked eye is not permitted. This should be determined before separating the bulk sample into test samples. + +=== Physical and chemical characteristics + +==== {blank} + +The mass fraction of moisture, determined in accordance with <>, using an oven complying with the requirements of <>, shall not be greater than 15 %.footnote:[Formerly denoted as 15 % (m/m).] + +//Convert table1 into an internal reference +The mass fraction of extraneous matter and defective kernels in husked and milled rice, whether or not parboiled, shall not be greater than the values specified in table1. + +NOTE: Lower mass fractions of moisture are sometimes needed for certain destinations depending on the climate, duration of transport and storage. For further details, see <>, <> and <>. + +==== {blank} +// Create an internal reference to table1 +The defect tolerance for the categories considered shall not exceed the limits given in table1. + +NOTE: This table is based on <>. + +NOTE: Some commercial contracts require information in addition to that provided in this table. + +NOTE: Only full red husked (cargo) rice is considered in this table. + +//Create an anchor called table1 +[cols="<,^,^,^,^",options="header,footer",headerrows=2] +.Maximum permissible mass fraction of defects +|=== +.2+^|Defect 4+^| Maximum permissible mass fraction of defects in husked rice + +stem:[w_max] + +% +| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice +| Extraneous matter: organic | 1,0 | 0,5 | 1,0 | 0,5 +| Extraneous matter: inorganic | 0,5 | 0,5 | 0,5 | 0,5 +| Paddy | 2,5 | 0,3 | 2,5 | 0,3 +| Husked rice, non-parboiled | Not applicable | 1,0 | 1,0 | 1,0 +| Milled rice, non-parboiled | 1,0 | Not applicable | 1,0 | 1,0 +| Husked rice, parboiled | 1,0 | 1,0 | Not applicable | 1,0 +| Milled rice, parboiled | 1,0 | 1,0 | 1,0 | Not applicable +| Chips | 0,1 | 0,1 | 0,1 | 0,1 +| HDK | 2,0 footnote:defectsmass[The maximum permissible mass fraction of defects shall be determined with respect to the mass fraction obtained after milling.] | 2,0 | 2,0 footnote:defectsmass[] | 2,0 +| Damaged kernels | 4,0 | 3,0 | 4,0 | 3,0 +| Immature and/or malformed kernels | 8,0 | 2,0 | 8,0 | 2,0 +| Chalky kernels | 5,0 footnote:defectsmass[] | 5,0 | Not applicable | Not applicable +| Red kernels and red-streaked kernels | 12,0 | 12,0 | 12,0 footnote:defectsmass[] | 12,0 +| Partly gelatinized kernels | Not applicable | Not applicable | 11,0 footnote:defectsmass[] | 11,0 +| Pecks | Not applicable | Not applicable | 4,0 | 2,0 +| Waxy rice | 1,0 footnote:defectsmass[] | 1,0 | 1,0 footnote:defectsmass[] | 1,0 + +5+a| Live insects shall not be present. Dead insects shall be included in extraneous matter. +|=== + + + +[bibliography] +== Bibliography + +* [[[ISO6322-1,ISO 6322-1]]], _Storage of cereals and pulses -- Part 1: General recommendations for the keeping of cereals_ + +* [[[ISO6322-2,ISO 6322-2]]], _Storage of cereals and pulses -- Part 2: Practical recommendations_ + +* [[[ISO6322-3,ISO 6322-3]]], _Storage of cereals and pulses -- Part 3: Control of attack by pests_ + +// Add entries for ISO712, ISO7301, IEC61010-2 + diff --git a/tutorials/exercises_code/exercise-3-1.adoc b/tutorials/exercises_code/exercise-3-1.adoc new file mode 100644 index 00000000..22f9177e --- /dev/null +++ b/tutorials/exercises_code/exercise-3-1.adoc @@ -0,0 +1,20 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +== Specifications + +=== General, organoleptic and health characteristics + +Kernels of rice, weter parboiled, husked or milled, and whether whole or broken, shall be sound, clean and free from foreign odours or odour which indicates deterioration. + +The levels of additives and pesticide residues and other contaminants shall not exseed the maximum limits permitted in the country of destination. + +The presence of living insects which are visible to the naked eyes is not permitted. This should be determined before separating the bulk sample into test samples. \ No newline at end of file diff --git a/tutorials/exercises_code/exercise-3-2.adoc b/tutorials/exercises_code/exercise-3-2.adoc new file mode 100644 index 00000000..a9763158 --- /dev/null +++ b/tutorials/exercises_code/exercise-3-2.adoc @@ -0,0 +1,677 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +.Foreword +ISO (the International Organization for Standardization) +is a worldwide federation of national standards bodies (ISO member bodies). The work of preparing International Standards is normally carried out through ISO technical committees. Each member body interested in a subject for which a technical committee has been established has the right to be represented on that committee. International organizations, governmental and non-governmental, in liaison with ISO, also take part in the work. ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of electrotechnical standardization. + +The procedures used to develop this document and those intended for its further maintenance are described in the ISO/IEC Directives, Part 1. In particular the different approval criteria needed for the different types of ISO documents should be noted. This document was drafted in accordance with the editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives). + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights. Details of any patent rights identified during the development of the document will be in the Introduction and/or on the ISO list of patent declarations received (see www.iso.org/patents). + +Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement. + +For an explanation on the voluntary nature of standards, the meaning of ISO specific terms and expressions related to conformity assessment, as well as information about ISO's adherence to the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT) see the following URL: www.iso.org/iso/foreword.html. + +This document was prepared by Technical Committee ISO/TC {technical-committee-number}, _{technical-committee}_, Subcommittee SC {subcommittee-number}, _{subcommittee}_. + +This second edition cancels and replaces the first edition (ISO {docnumber}-{partnumber}:2009), which has been technically revised. + +The main changes compared to the previous edition are: + +* updated normative references; +* deletion of 4.3. + +A list of all parts in the ISO {docnumber} series can be found on the ISO website. + +[reviewer=ISO,date=2017-01-01,from=foreword,to=foreword] +**** +A Foreword shall appear in each document. The generic text is shown here. It does not contain requirements, recommendations or permissions. + +For further information on the Foreword, see *ISO/IEC Directives, Part 2, 2016, Clause 12.* +**** + + +== Introduction + +This document was developed in response to worldwide demand for minimum specifications for rice traded internationally, since most commercial bulks of grain, which have not been screened or aspirated, contain a proportion of other grains, weed seeds, chaff, straw, stones, sand, etc. The vegetable materials can have physical and biological properties which differ from those of the main constituent and can therefore affect the storage behaviour. + +Rice is a permanent host to a considerable microflora; most of these microorganisms are cosmopolitan, the majority are innocuous, but some produce harmful by-products. Microflora communities present on freshly harvested rice include many types of bacteria, moulds and yeasts. While the rice is ripening and its moisture content is falling, the number of field microorganisms, mainly bacteria, diminishes. When the rice is harvested, it is invaded by storage microorganisms and the field microflora gradually dies out. If the mass fraction of moisture (formerly expressed as moisture content) is less than 18 %, the microflora does not multiply, whereas above 18 % it does so rapidly. Thus, at harvest, the qualitative and the quantitative composition of the microflora depends more upon ecological factors than upon the variety of the rice. During transport and storage, additions to the microfloral population occur. Microorganisms on the rice at harvest tend to die out during storage and are replaced by microorganisms adapted to storage conditions. + +Storage losses have been estimated as being an average of 5 %, and as much as 30 %, especially in countries with climates favourable to the rapid development of agents of deterioration and where storage techniques are poorly developed, such as developing countries in the damp tropics. The magnitude of these figures highlights the need to promote throughout the world a rapid improvement in techniques of conservation. + + +The International Organization for Standardization (ISO) draws attention to the fact that it is claimed that compliance with this document may involve the use of a patent concerning sample dividers given in <> and shown in <>. + +ISO takes no position concerning the evidence, validity and scope of this patent right. + +The holder of this patent right has assured ISO that he/she is willing to negotiate licences under reasonable and non-discriminatory terms and conditions with applicants throughout the world. In this respect, the statement of the holder of this patent right is registered with ISO. Information may be obtained from: + +[align=left] +Vache Equipment + +Fictitious + +World + +mailto:gehf@vacheequipment.fic[] + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights other than those identified above. ISO shall not be held responsible for identifying any or all such patent rights. + + +== Scope + +This document specifies minimum requirements and test methods for rice (_Oryza sativa L._). + +It is applicable to husked rice, husked parboiled rice, milled rice and milled parboiled rice, suitable for human consumption, directly or after reconditioning. + +It is not applicable to cooked rice products. + +[bibliography] +== Normative references + +* [[[ISO712,ISO 712]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_ + +* [[[ISO6646, ISO 6646]]], _Rice -- Determination of the potential milling yield from paddy and from husked rice_ + +* [[[ISO8351-1,ISO 8351-1:1994]]], _Packaging -- Method of specification for sacks -- Part 1: Paper sacks_ + +* [[[ISO8351-2,ISO 8351-2]]], _Packaging -- Method of specification for sacks -- Part 2: Sacks made from thermoplastic flexible film_ + +* [[[ISO16634,ISO 16634:--]]] footnote:[Under preparation. (Stage at the time of publication ISO/DIS 16634)], _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_ + +* [[[ISO20483,ISO 20483:2013]]], _Cereals and pulses -- Determination of the nitrogen content and calculation of the crude protein content -- Kjeldahl method_ + +* [[[ISO24333,ISO 24333:2009]]], _Cereals and cereal products -- Sampling_ + +== Terms and definitions + +[[paddy]] +=== paddy +alt:[paddy rice] +alt:[rough rice] + +rice retaining its husk after threshing + +[.source] +<> + +[[husked_rice]] +=== husked rice +deprecated:[cargo rice] + +term:[paddy] from which the husk only has been removed + +[.source] +<>, The term "cargo rice" is shown as deprecated, and Note 1 to entry is not included here + +=== milled rice +alt:[white rice] + +term:[husked rice] from which almost all of the bran and embryo have been removed by milling + +[.source] +<> + +=== parboiled rice + +rice whose starch has been fully gelatinized by soaking term:[paddy] rice or term:[husked rice] in water followed by a heat treatment and a drying process + +=== waxy rice +variety of rice whose kernels have a white and opaque appearance + +NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking. + +=== extraneous matter +alt:[EM] +domain:[rice] + +organic and inorganic components other than whole or broken kernels + +[example] +Foreign seeds, husks, bran, sand, dust. + +[[HDK]] +=== HDK +alt:[heat-damaged kernel] + +kernel, whole or broken, which has changed its normal colour as a result of heating + +NOTE: This category includes whole or broken kernels that are yellow due to alteration. Parboiled rice in a batch of non-parboiled rice is also included in this category. + +=== damaged kernel +kernel, whole or broken, showing obvious deterioration due to moisture, pests, disease or other causes, but excluding term:[HDK] + +=== immature kernel +alt:[unripe kernel] + +kernel, whole or broken, which is unripe and/or underdeveloped + +=== husked rice yield +amount of husked rice obtained from paddy + +// all terms and defs references are dated +[.source] +<> + +=== nitrogen content +quantity of nitrogen determined after application of the procedure described + +NOTE: It is expressed as a mass fraction of dry product, as a percentage. + +[.source] +<> + +=== crude protein content +quantity of crude protein obtained from the nitrogen content as determined by applying the specified method, calculated by multiplying this content by an appropriate factor depending on the type of cereal or pulse + +NOTE: It is expressed as a mass fraction of dry product, as a percentage. + +[.source] +<> + +[[gelatinization]] +=== gelatinization +hydration process conferring the jelly-like state typical of the coagulated colloids, which are named "gels", on kernels + +NOTE: See <>. + +[.source] +<> + +[[gel_state]] +=== gel state +condition reached as a consequence of term:[gelatinization], when the kernel is fully transparent and absolutely free from whitish and opaque granules after being pressed between two glass sheets + +[.source] +<> + +=== gelatinization time +stem:[t_90] + +time necessary for 90 % of the kernels to pass from their natural state to the term:[gel state] + +[.source] +<> + + +== Specifications + +=== General, organoleptic and health characteristics + +Kernels of rice, whether parboiled, husked or milled, and whether whole or broken, shall be sound, clean and free from foreign odours or odour which indicates deterioration. + +The levels of additives and pesticide residues and other contaminants shall not exceed the maximum limits permitted in the country of destination. + +The presence of living insects which are visible to the naked eye is not permitted. This should be determined before separating the bulk sample into test samples. + +=== Physical and chemical characteristics + +==== {blank} + +The mass fraction of moisture, determined in accordance with <>, using an oven complying with the requirements of <>, shall not be greater than 15 %.footnote:[Formerly denoted as 15 % (m/m).] + +The mass fraction of extraneous matter and defective kernels in husked and milled rice, whether or not parboiled, determined in accordance with <>, shall not be greater than the values specified in <>. + +NOTE: Lower mass fractions of moisture are sometimes needed for certain destinations depending on the climate, duration of transport and storage. For further details, see <>, <> and <>. + +==== {blank} + +The defect tolerance for the categories considered, and determined in accordance with the method given in <>, shall not exceed the limits given in <>. + +[#table1] +[cols="<,^,^,^,^",options="header,footer",headerrows=2] +.Maximum permissible mass fraction of defects +|=== +.2+^|Defect 4+^| Maximum permissible mass fraction of defects in husked rice + +stem:[w_max] + +% +| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice + +| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] +| 1,0 | 0,5 | 1,0 | 0,5 + +| Extraneous matter: inorganic footnote:[Inorganic extraneous matter includes stones, sand, dust, etc.] +| 0,5 | 0,5 | 0,5 | 0,5 + +| Paddy | 2,5 | 0,3 | 2,5 | 0,3 +| Husked rice, non-parboiled | Not applicable | 1,0 | 1,0 | 1,0 +| Milled rice, non-parboiled | 1,0 | Not applicable | 1,0 | 1,0 +| Husked rice, parboiled | 1,0 | 1,0 | Not applicable | 1,0 +| Milled rice, parboiled | 1,0 | 1,0 | 1,0 | Not applicable +| Chips | 0,1 | 0,1 | 0,1 | 0,1 +| HDK | 2,0 footnote:defectsmass[The maximum permissible mass fraction of defects shall be determined with respect to the mass fraction obtained after milling.] | 2,0 | 2,0 footnote:defectsmass[] | 2,0 +| Damaged kernels | 4,0 | 3,0 | 4,0 | 3,0 +| Immature and/or malformed kernels | 8,0 | 2,0 | 8,0 | 2,0 +| Chalky kernels | 5,0 footnote:defectsmass[] | 5,0 | Not applicable | Not applicable +| Red kernels and red-streaked kernels | 12,0 | 12,0 | 12,0 footnote:defectsmass[] | 12,0 +| Partly gelatinized kernels | Not applicable | Not applicable | 11,0 footnote:defectsmass[] | 11,0 +| Pecks | Not applicable | Not applicable | 4,0 | 2,0 +| Waxy rice | 1,0 footnote:defectsmass[] | 1,0 | 1,0 footnote:defectsmass[] | 1,0 + +5+a| Live insects shall not be present. Dead insects shall be included in extraneous matter. +|=== + +NOTE: This table is based on <>. + +NOTE: Some commercial contracts require information in addition to that provided in this table. + +NOTE: Only full red husked (cargo) rice is considered in this table. + + +[[clause5]] +== Sampling +Sampling shall be carried out in accordance with <>. + +== Test methods + +=== Moisture content + +Determine the mass fraction of moisture in accordance with the method specified in <>. + +=== Waxy rice content + +Determine the mass fraction of waxy rice. <> gives an example of a suitable method. + +=== Nitrogen content and crude protein content + +Determine the nitrogen content and crude protein content in accordance with either <>, or <>. For details on the determination of protein content using the Kjeldahl method, see Reference <> in the Bibliography. For details concerning the use of the Dumas method, see References <> and <>. + +// can't join two bibliographic localities with "and" currently +Calculate the crude protein content of the dry product by multiplying the value of the nitrogen content by the conversion factor specified in <> and Table C.1, that is adapted to the type of cereals or pulses <><> and to their use. + +=== Gelatinization time + +Determine the gelatinization time, stem:[t_90], for rice kernels during cooking. An example of a typical curve is given in <>. Three typical stages of gelatinization are shown in <>. + +Report the results as specified in <>. + +=== Husked rice yield + +==== Determination + +CAUTION: Only use paddy or parboiled rice for the determination of husked rice yield. + +Determine the husked rice yield in accordance with <>. + +==== Precision + +===== Interlaboratory test + +The results of an interlaboratory test are given in <> for information + +===== Repeatability + +The absolute difference between two independent single test results, obtained using the same method on identical test material in the same laboratory by the same operator using the same equipment within a short interval of time, shall not exceed the arithmetic mean of the values for stem:[r] obtained from the interlaboratory study for husked rice in more than 5 % of cases: + +[stem%unnumbered] +++++ +r = 1 % +++++ + +where + +stem:[r]:: is the repeatability limit. + +===== Reproducibility + +The absolute difference between two single test results, obtained using the same method on identical test material in different laboratories by different operators using different equipment, shall not exceed the arithmetic mean of the values for stem:[R] obtained from the interlaboratory study in more than 5 % of cases: + +[stem%unnumbered] +++++ +R = 3 % +++++ + +where + +stem:[R]:: is the reproducibility limit. + +[[clause7]] +== Test report + +For each test method, the test report shall specify the following: + +[loweralpha] +. all information necessary for the complete identification of the sample; +. a reference to this document (i.e. ISO {docnumber}-{partnumber}); +. the sampling method used; +. the test method used; +. the test result(s) obtained or, if the repeatability has been checked, the final quoted result obtained; +. all operating details not specified in this document, or regarded as optional, together with details of any incidents which may have influenced the test result(s); +. any unusual features (anomalies) observed during the test; +. the date of the test. + +== Packaging + +The packaging shall not transmit any odour or flavour to the product and shall not contain substances which may damage the product or constitute a health risk. + +If bags are used, they shall comply with the requirements of <>, or <>, as appropriate. + +== Marking + +The packages shall be marked or labelled as required by the country of destination. + +[[AnnexA]] +[appendix,obligation=normative] +== Determination of defects + +=== Principle + +Extraneous matter, broken kernels, damaged kernels and other kinds of rice are separated manually according to the following types: husked rice, milled rice, husked parboiled rice and milled parboiled rice. Each type is then weighed. + +=== Apparatus + +The usual laboratory apparatus and, in particular, the following. + +[%inline-header] +[[AnnexA-2-1]] +==== Sample divider, + +consisting of a conical sample divider or multiple-slot sample divider with a distribution system, e.g. "Split-it-right" sample divider, such as that shown in <>. + +[%inline-header] +==== Sieve, + +with round perforations of diameter 1,4 mm. + +[%inline-header] +==== Tweezers. + +[%inline-header] +==== Scalpel. + +[%inline-header] +==== Paintbrush. + +[%inline-header] +[[AnnexA-2-6]] +==== Steel bowls, + +of diameter 100 mm ± 5 mm; seven per test sample. + +[%inline-header] +==== Balance, + +which can be read to the nearest 0,01 g. + +=== Sampling + +See <>. + +=== Procedure + +[[AnnexA-4-1]] +==== Preparation of test sample + +Carefully mix the laboratory sample to make it as uniform as possible, then proceed to reduce it, using a divider (<>), until a quantity of about 30 g is obtained. + +All parts of kernels which get stuck in the perforations of a sieve should be considered to be retained by the sieve. + +[[figureA-1]] +.Split-it-right sample divider +image::images/a1.png[Alt1] + +=== Determination + +Weigh, to the nearest 0,1 g, one of the test samples obtained in accordance with <> and separate the different defects into the bowls (<>). When a kernel has several defects, classify it in the defect category for which the maximum permissible value is the lowest (see <>). + +Weigh, to the nearest 0,01 g, the fractions so obtained. + +=== Calculation + +Express the mass fraction of each defect using <>: + +[[formulaA-1,A.1]] +[stem] +++++ +w = (m_D) / (m_s) +++++ + +where + +stem:[w]:: is the mass fraction of grains with a particular defect in the test sample; +stem:[m_D]:: is the mass, in grams, of grains with that defect; +stem:[m_S]:: is the mass, in grams, of the test sample. + +=== Test report + +Report the results as specified in <>. + +[[AnnexB]] +[appendix,obligation=informative] +== Determination of the waxy rice content of parboiled rice + +=== Principle + +Waxy rice kernels have a reddish brown colour when stained in an iodine solution, while non-waxy rice kernels show a dark blue colour. + +=== Apparatus + +The usual laboratory apparatus and, in particular, the following. + +[%inline-header] +[[AnnexB-2-1]] +==== Balance, + +capable of weighing to the nearest 0,01 g. + +[%inline-header] +[[AnnexB-2-2]] +==== Glass beaker, + +of capacity 250 ml. + +[%inline-header] +[[AnnexB-2-3]] +==== Small white colour bowls, + +or any white colour container of a suitable size. + +[%inline-header] +[[AnnexB-2-4]] +==== Wire sieve, + +with long rounded apertures of (1 mm stem:[{:(+0.02),(0):}] mm) × (20 mm stem:[{:(+2),(-1):}] mm). + +[%inline-header] +[[AnnexB-2-5]] +==== Stirrer rod. + +[%inline-header] +[[AnnexB-2-6]] +==== Tweezers or forceps. + +[%inline-header] +[[AnnexB-2-7]] +==== Tissue paper. + +=== Reagents + +WARNING: Direct contact of iodine with skin can cause lesions so care should be taken in handling iodine. Iodine vapour is very irritating to eyes and mucous membranes. + +[%inline-header] +[[AnnexB-3-1]] +==== Deionized water, + +Grade 3 quality as specified in <>. + +[%inline-header] +[[AnnexB-3-2]] +==== Iodine stock solution, + +containing a mass fraction of 4,1 % iodine and 6,3 % potassium iodide in deionized water such as Lugols.footnote:[Lugols is an example of a suitable product available commercially. This information is given for the convenience of users of this document and does not constitute an endorsement by ISO of this product.] + +[%inline-header] +[[AnnexB-3-3]] +==== Iodine working solution, + +obtained by diluting the stock solution (<>) two times (by volume) with deionized water (<>). + +Prepare fresh daily. + +=== Sampling + +Sampling shall be carried out in accordance with <>. + +=== Determination + +==== {blank} +Weigh a portion of about 100 g of milled rice and put it into a glass beaker (<>). + +==== {blank} +Add enough iodine working solution (<>) to soak the kernels, and stir (<>) until all the kernels are submerged under the solution. Let the kernels soak in the solution for 30 s. + +==== {blank} +Pour the rice and solution into a wire sieve (<>), and shake the basket slightly in order to drain out the solution. Then place the wire sieve on a piece of tissue paper (<>) to absorb the excess liquid. + +==== {blank} +Pour the stained kernels into a bowl (<>). Using tweezers or forceps (<>), separate the reddish brown kernels of waxy rice from the dark blue kernels of non-waxy rice. + +==== {blank} +Weigh the waxy rice portion (stem:[m_1]) and the non-waxy rice portion (stem:[m_2]) to the nearest 0,1 g. + +=== Calculation + +Calculate the mass fraction, expressed as a percentage, of the waxy rice, stem:[w_(wax)], using <>: + +[[formulaB-1,B.1]] +[stem] +++++ +w_(wax) = (m_1) / (m_1 + m_2) xx 100 +++++ + +where + +stem:[m_1]:: is the mass, expressed in grams, of the waxy rice portion; +stem:[m_2]:: is the mass, expressed in grams, of the non-waxy rice portion. + +=== Test report + +Report the results as specified in <>, giving the results calculated using <>. + +[[AnnexC]] +[appendix,obligation=informative] +== Gelatinization + +<> gives an example of a typical gelatinization curve. <> shows the three stages of gelatinization. + +[[figureC-1]] +.Typical gelatinization curve +image::images/b1.png[Alt2] +footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.] + +*Key* + +stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent +stem:[t]:: cooking time, expressed in minutes +stem:[t_90]:: time required to gelatinize 90 % of the kernels +P:: point of the curve corresponding to a cooking time of stem:[t_90] + +NOTE: These results are based on a study carried out on three different types of kernel. + +[[figureC-2]] +.Stages of gelatinization +==== +.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels) +image::images/c2-a.png[Alt3] + +.Intermediate stages: Some fully gelatinized kernels are visible +image::images/c2-b.png[Alt4] + +.Final stages: All kernels are fully gelatinized +image::images/c2-c.png[Alt5] + +==== + +[[AnnexD]] +[appendix,obligation=informative] +== Results of interlaboratory test for husked rice yields + +An interlaboratory test <> was carried out by the ENR [Rice Research Centre (Italy)] in accordance with <> and <>, with the participation of 15 laboratories. Each laboratory carried out three determinations on four different types of kernel. The statistical results are shown in <>. + +[[tableD-1]] +[cols="<,^,^,^,^",headerrows=2] +.Repeatability and reproducibility of husked rice yield +|=== +.2+^| Description 4+| Rice sample +| Arborio | Drago footnote:[Parboiled rice.] | Balilla | Thaibonnet + +| Number of laboratories retained after eliminating outliers | 13 | 11 | 13 | 13 +| Mean value, g/100 g | 81,2 | 82,0 | 81,8 | 77,7 +| Standard deviation of repeatability, stem:[s_r], g/100 g | 0,41 | 0,15 | 0,31 | 0,53 +| Coefficient of variation of repeatability, % | 0,5 | 0,2 | 0,4 | 0,7 +| Repeatability limit, stem:[r] (= 2,83 stem:[s_r]) | 1,16 | 0,42 | 0,88 | 1,50 +| Standard deviation of reproducibility, stem:[s_R], g/100 g | 1,02 | 0,20 | 0,80 | 2,14 +| Coefficient of variation of reproducibility, % | 1,3 | 0,2 | 1,0 | 2,7 +| Reproducibility limit, stem:[R] (= 2,83 stem:[s_R]) | 2,89 | 0,57 | 2,26 | 6,06 +|=== + +[appendix,obligation=informative] +== Extraneous information + +_This appendix is not in the original Rice model document, and is inserted to illustrate elements absent from +that document: block quotes, source code, and examples._ + +[quote, ISO, "ISO7301,clause 1"] +_____ +This International Standard gives the minimum specifications for rice (_Oryza sativa_ L.) which is subject to international trade. It is applicable to the following types: husked rice and milled rice, parboiled or not, intended for direct human consumption. It is neither applicable to other products derived from rice, nor to waxy rice (glutinous rice). +_____ + +[%appendix] +=== Sample code + +[[samplecode]] +.Sample Code +==== + +[source,ruby] +-- +puts "Hello, world." +%w{a b c}.each do |x| <1> + puts x +end +-- +<1> This is an annotation +==== + + + +[bibliography] +== Bibliography + +* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_ + +* [[[ISO5725-1,ISO 5725-1]]], _Accuracy (trueness and precision) of measurement methods and results -- Part 1: General principles and definitions_ + +* [[[ISO5725-2,ISO 5725-2]]], _Accuracy (trueness and precision) of measurement methods and results -- Part 2: Basic method for the determination of repeatability and reproducibility of a standard measurement method_ + +* [[[ISO6322-1,ISO 6322-1]]], _Storage of cereals and pulses -- Part 1: General recommendations for the keeping of cereals_ + +* [[[ISO6322-2,ISO 6322-2]]], _Storage of cereals and pulses -- Part 2: Practical recommendations_ + +* [[[ISO6322-3,ISO 6322-3]]], _Storage of cereals and pulses -- Part 3: Control of attack by pests_ + +* [[[ISO7301,ISO 7301:2011]]], _Rice -- Specification_ + +* [[[ISO14864,ISO 14864:1998]]], _Rice -- Evaluation of gelatinization time of kernels during cooking_ + +* [[[IEC61010-2,IEC 61010-2:1998]]], _Safety requirements for electric equipment for measurement, control, and laboratory use -- Part 2: Particular requirements for laboratory equipment for the heating of material_ + +* [[[ref10,10]]] [smallcap]#Standard No I.C.C 167#. _Determination of the protein content in cereal and cereal products for food and animal feeding stuffs according to the Dumas combustion method_ (see http://www.icc.or.at) + +* [[[ref11,11]]] Nitrogen-ammonia-protein modified Kjeldahl method -- Titanium oxide and copper sulfate catalyst. _Official Methods and Recommended Practices of the AOCS_ (ed. Firestone, D.E.), AOCS Official Method Ba Ai 4-91, 1997, AOCS Press, Champaign, IL + +* [[[ref12,12]]] [smallcap]#Berner D.L., & Brown J.# Protein nitrogen combustion method collaborative study I. Comparison with Smalley total Kjeldahl nitrogen and combustion results. _J. Am. Oil Chem. Soc._ 1994, *71* (11) pp 1291-1293 + +* [[[ref13,13]]] [smallcap]#Buckee G.K.# Determination of total nitrogen in barley, malt and beer by Kjeldahl procedures and the Dumas combustion method -- Collaborative trial. _J. Inst. Brew._ 1994, *100* (2) pp 57-64 + +* [[[ref14,14]]] [smallcap]#Frister H.# _Direct determination of nitrogen content by Dumas analysis; Interlaboratory study on precision characteristics_. AOAC International, Europe Section 4th International Symposium, Nyon, Switzerland, 1994, 33 pp + +* [[[ref15,15]]] [smallcap]#Ranghino F.# Evaluation of rice resistance to cooking, based on the gelatinization time of kernels. _Il Riso_. 1966, *XV* pp 117-127 + +* [[[ref16,16]]] [smallcap]#Tkachuk R.# Nitrogen-to-protein conversion factors for cereals and oilseed meals. _Cereal Chem._ 1969, *46* (4) pp 419-423 diff --git a/tutorials/exercises_code/exercise-4.adoc b/tutorials/exercises_code/exercise-4.adoc new file mode 100644 index 00000000..179e7d2b --- /dev/null +++ b/tutorials/exercises_code/exercise-4.adoc @@ -0,0 +1,681 @@ += Sample document: Rice +Author +:technical-committee: Food products +:fullname: Author Name +:mn-document-class: standoc +:doctype: document +:language: en +:created-date: 2021-07-31 +:copyright-holder: Ribose Inc. +:copyright-year: 2021 + +[[prefatory-clause]] +.Foreword +ISO (the International Organization for Standardization) +is a worldwide federation of national standards bodies (ISO member bodies). The work of preparing International Standards is normally carried out through ISO technical committees. Each member body interested in a subject for which a technical committee has been established has the right to be represented on that committee. International organizations, governmental and non-governmental, in liaison with ISO, also take part in the work. ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of electrotechnical standardization. + +The procedures used to develop this document and those intended for its further maintenance are described in the ISO/IEC Directives, Part 1. In particular the different approval criteria needed for the different types of ISO documents should be noted. This document was drafted in accordance with the editorial rules of the ISO/IEC Directives, Part 2 (see www.iso.org/directives). + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights. Details of any patent rights identified during the development of the document will be in the Introduction and/or on the ISO list of patent declarations received (see www.iso.org/patents). + +Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement. + +For an explanation on the voluntary nature of standards, the meaning of ISO specific terms and expressions related to conformity assessment, as well as information about ISO's adherence to the World Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT) see the following URL: www.iso.org/iso/foreword.html. + +This document was prepared by Technical Committee _{technical-committee}_. + +This second edition cancels and replaces the first edition, which has been technically revised. + +The main changes compared to the previous edition are: + +* updated normative references; +* deletion of 4.3. + +A list of all parts in the ISO {docnumber} series can be found on the ISO website. + +[reviewer=ISO,date=2017-01-01,from=foreword,to=foreword] +**** +A Foreword shall appear in each document. The generic text is shown here. It does not contain requirements, recommendations or permissions. + +For further information on the Foreword, see *ISO/IEC Directives, Part 2, 2016, Clause 12.* +**** + +[[introduction]] +== Introduction + +This document was developed in response to worldwide demand for minimum specifications for rice traded internationally, since most commercial bulks of grain, which have not been screened or aspirated, contain a proportion of other grains, weed seeds, chaff, straw, stones, sand, etc. The vegetable materials can have physical and biological properties which differ from those of the main constituent and can therefore affect the storage behaviour. + +Rice is a permanent host to a considerable microflora; most of these microorganisms are cosmopolitan, the majority are innocuous, but some produce harmful by-products. Microflora communities present on freshly harvested rice include many types of bacteria, moulds and yeasts. While the rice is ripening and its moisture content is falling, the number of field microorganisms, mainly bacteria, diminishes. When the rice is harvested, it is invaded by storage microorganisms and the field microflora gradually dies out. If the mass fraction of moisture (formerly expressed as moisture content) is less than 18 %, the microflora does not multiply, whereas above 18 % it does so rapidly. Thus, at harvest, the qualitative and the quantitative composition of the microflora depends more upon ecological factors than upon the variety of the rice. During transport and storage, additions to the microfloral population occur. Microorganisms on the rice at harvest tend to die out during storage and are replaced by microorganisms adapted to storage conditions. + +Storage losses have been estimated as being an average of 5 %, and as much as 30 %, especially in countries with climates favourable to the rapid development of agents of deterioration and where storage techniques are poorly developed, such as developing countries in the damp tropics. The magnitude of these figures highlights the need to promote throughout the world a rapid improvement in techniques of conservation. + + +The International Organization for Standardization (ISO) draws attention to the fact that it is claimed that compliance with this document may involve the use of a patent concerning sample dividers given in <> and shown in <>. + +ISO takes no position concerning the evidence, validity and scope of this patent right. + +The holder of this patent right has assured ISO that he/she is willing to negotiate licences under reasonable and non-discriminatory terms and conditions with applicants throughout the world. In this respect, the statement of the holder of this patent right is registered with ISO. Information may be obtained from: + +[align=left] +Vache Equipment + +Fictitious + +World + +mailto:gehf@vacheequipment.fic[] + +Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights other than those identified above. ISO shall not be held responsible for identifying any or all such patent rights. + + +== Scope + +This document specifies minimum requirements and test methods for rice (_Oryza sativa L._). + +It is applicable to husked rice, husked parboiled rice, milled rice and milled parboiled rice, suitable for human consumption, directly or after reconditioning. + +It is not applicable to cooked rice products. + +// TODO: no such file +// include::scope.adoc[] + +[bibliography] +== Normative references + +* [[[ISO712,ISO 712]]], _Cereals and cereal products -- Determination of moisture content -- Reference method_ + +* [[[ISO6646, ISO 6646]]], _Rice -- Determination of the potential milling yield from paddy and from husked rice_ + +* [[[ISO8351-1,ISO 8351-1:1994]]], _Packaging -- Method of specification for sacks -- Part 1: Paper sacks_ + +* [[[ISO8351-2,ISO 8351-2]]], _Packaging -- Method of specification for sacks -- Part 2: Sacks made from thermoplastic flexible film_ + +* [[[ISO16634,ISO 16634:--]]] footnote:[Under preparation. (Stage at the time of publication ISO/DIS 16634)], _Cereals, pulses, milled cereal products, oilseeds and animal feeding stuffs -- Determination of the total nitrogen content by combustion according to the Dumas principle and calculation of the crude protein content_ + +* [[[ISO20483,ISO 20483:2013]]], _Cereals and pulses -- Determination of the nitrogen content and calculation of the crude protein content -- Kjeldahl method_ + +* [[[ISO24333,ISO 24333:2009]]], _Cereals and cereal products -- Sampling_ + +== Terms and definitions + +[[paddy]] +=== paddy +alt:[paddy rice] +alt:[rough rice] + +rice retaining its husk after threshing + +[.source] +<> + +[[husked_rice]] +=== husked rice +deprecated:[cargo rice] + +term:[paddy] from which the husk only has been removed + +[.source] +<>, The term "cargo rice" is shown as deprecated, and Note 1 to entry is not included here + +=== milled rice +alt:[white rice] + +term:[husked rice] from which almost all of the bran and embryo have been removed by milling + +[.source] +<> + +=== parboiled rice + +rice whose starch has been fully gelatinized by soaking term:[paddy] rice or term:[husked rice] in water followed by a heat treatment and a drying process + +=== waxy rice +variety of rice whose kernels have a white and opaque appearance + +NOTE: The starch of waxy rice consists almost entirely of amylopectin. The kernels have a tendency to stick together after cooking. + +=== extraneous matter +alt:[EM] +domain:[rice] + +organic and inorganic components other than whole or broken kernels + +[example] +Foreign seeds, husks, bran, sand, dust. + +[[HDK]] +=== HDK +alt:[heat-damaged kernel] + +kernel, whole or broken, which has changed its normal colour as a result of heating + +NOTE: This category includes whole or broken kernels that are yellow due to alteration. Parboiled rice in a batch of non-parboiled rice is also included in this category. + +=== damaged kernel +kernel, whole or broken, showing obvious deterioration due to moisture, pests, disease or other causes, but excluding term:[HDK] + +=== immature kernel +alt:[unripe kernel] + +kernel, whole or broken, which is unripe and/or underdeveloped + +=== husked rice yield +amount of husked rice obtained from paddy + +// all terms and defs references are dated +[.source] +<> + +=== nitrogen content +quantity of nitrogen determined after application of the procedure described + +NOTE: It is expressed as a mass fraction of dry product, as a percentage. + +[.source] +<> + +=== crude protein content +quantity of crude protein obtained from the nitrogen content as determined by applying the specified method, calculated by multiplying this content by an appropriate factor depending on the type of cereal or pulse + +NOTE: It is expressed as a mass fraction of dry product, as a percentage. + +[.source] +<> + +[[gelatinization]] +=== gelatinization +hydration process conferring the jelly-like state typical of the coagulated colloids, which are named "gels", on kernels + +NOTE: See <>. + +[.source] +<> + +[[gel_state]] +=== gel state +condition reached as a consequence of term:[gelatinization], when the kernel is fully transparent and absolutely free from whitish and opaque granules after being pressed between two glass sheets + +[.source] +<> + +=== gelatinization time +stem:[t_90] + +time necessary for 90 % of the kernels to pass from their natural state to the term:[gel state] + +[.source] +<> + + +== Specifications + +=== General, organoleptic and health characteristics + +Kernels of rice, whether parboiled, husked or milled, and whether whole or broken, shall be sound, clean and free from foreign odours or odour which indicates deterioration. + +The levels of additives and pesticide residues and other contaminants shall not exceed the maximum limits permitted in the country of destination. + +The presence of living insects which are visible to the naked eye is not permitted. This should be determined before separating the bulk sample into test samples. + +=== Physical and chemical characteristics + +==== {blank} + +The mass fraction of moisture, determined in accordance with <>, using an oven complying with the requirements of <>, shall not be greater than 15 %.footnote:[Formerly denoted as 15 % (m/m).] + +The mass fraction of extraneous matter and defective kernels in husked and milled rice, whether or not parboiled, determined in accordance with <>, shall not be greater than the values specified in <>. + +NOTE: Lower mass fractions of moisture are sometimes needed for certain destinations depending on the climate, duration of transport and storage. For further details, see <>, <> and <>. + +==== {blank} + +The defect tolerance for the categories considered, and determined in accordance with the method given in <>, shall not exceed the limits given in <>. + +[#table1] +[cols="<,^,^,^,^",options="header,footer",headerrows=2] +.Maximum permissible mass fraction of defects +|=== +.2+^|Defect 4+^| Maximum permissible mass fraction of defects in husked rice + +stem:[w_max] + +% +| in husked rice | in milled rice (non-glutinous) | in husked parboiled rice | in milled parboiled rice + +| Extraneous matter: organic footnote:[Organic extraneous matter includes foreign seeds, husks, bran, parts of straw, etc.] +| 1,0 | 0,5 | 1,0 | 0,5 + +| Extraneous matter: inorganic footnote:[Inorganic extraneous matter includes stones, sand, dust, etc.] +| 0,5 | 0,5 | 0,5 | 0,5 + +| Paddy | 2,5 | 0,3 | 2,5 | 0,3 +| Husked rice, non-parboiled | Not applicable | 1,0 | 1,0 | 1,0 +| Milled rice, non-parboiled | 1,0 | Not applicable | 1,0 | 1,0 +| Husked rice, parboiled | 1,0 | 1,0 | Not applicable | 1,0 +| Milled rice, parboiled | 1,0 | 1,0 | 1,0 | Not applicable +| Chips | 0,1 | 0,1 | 0,1 | 0,1 +| HDK | 2,0 footnote:defectsmass[The maximum permissible mass fraction of defects shall be determined with respect to the mass fraction obtained after milling.] | 2,0 | 2,0 footnote:defectsmass[] | 2,0 +| Damaged kernels | 4,0 | 3,0 | 4,0 | 3,0 +| Immature and/or malformed kernels | 8,0 | 2,0 | 8,0 | 2,0 +| Chalky kernels | 5,0 footnote:defectsmass[] | 5,0 | Not applicable | Not applicable +| Red kernels and red-streaked kernels | 12,0 | 12,0 | 12,0 footnote:defectsmass[] | 12,0 +| Partly gelatinized kernels | Not applicable | Not applicable | 11,0 footnote:defectsmass[] | 11,0 +| Pecks | Not applicable | Not applicable | 4,0 | 2,0 +| Waxy rice | 1,0 footnote:defectsmass[] | 1,0 | 1,0 footnote:defectsmass[] | 1,0 + +5+a| Live insects shall not be present. Dead insects shall be included in extraneous matter. +|=== + +NOTE: This table is based on <>. + +NOTE: Some commercial contracts require information in addition to that provided in this table. + +NOTE: Only full red husked (cargo) rice is considered in this table. + + +[[clause5]] +== Sampling +Sampling shall be carried out in accordance with <>. + +== Test methods + +=== Moisture content + +Determine the mass fraction of moisture in accordance with the method specified in <>. + +=== Waxy rice content + +Determine the mass fraction of waxy rice. <> gives an example of a suitable method. + +=== Nitrogen content and crude protein content + +Determine the nitrogen content and crude protein content in accordance with either <>, or <>. For details on the determination of protein content using the Kjeldahl method, see Reference <> in the Bibliography. For details concerning the use of the Dumas method, see References <> and <>. + +// can't join two bibliographic localities with "and" currently +Calculate the crude protein content of the dry product by multiplying the value of the nitrogen content by the conversion factor specified in <> and Table C.1, that is adapted to the type of cereals or pulses <><> and to their use. + +=== Gelatinization time + +Determine the gelatinization time, stem:[t_90], for rice kernels during cooking. An example of a typical curve is given in <>. Three typical stages of gelatinization are shown in <>. + +Report the results as specified in <>. + +=== Husked rice yield + +==== Determination + +CAUTION: Only use paddy or parboiled rice for the determination of husked rice yield. + +Determine the husked rice yield in accordance with <>. + +==== Precision + +===== Interlaboratory test + +The results of an interlaboratory test are given in <> for information + +===== Repeatability + +The absolute difference between two independent single test results, obtained using the same method on identical test material in the same laboratory by the same operator using the same equipment within a short interval of time, shall not exceed the arithmetic mean of the values for stem:[r] obtained from the interlaboratory study for husked rice in more than 5 % of cases: + +[stem%unnumbered] +++++ +r = 1 % +++++ + +where + +stem:[r]:: is the repeatability limit. + +===== Reproducibility + +The absolute difference between two single test results, obtained using the same method on identical test material in different laboratories by different operators using different equipment, shall not exceed the arithmetic mean of the values for stem:[R] obtained from the interlaboratory study in more than 5 % of cases: + +[stem%unnumbered] +++++ +R = 3 % +++++ + +where + +stem:[R]:: is the reproducibility limit. + +[[clause7]] +== Test report + +For each test method, the test report shall specify the following: + +[loweralpha] +. all information necessary for the complete identification of the sample; +. a reference to this document (i.e. ISO {docnumber}-{partnumber}); +. the sampling method used; +. the test method used; +. the test result(s) obtained or, if the repeatability has been checked, the final quoted result obtained; +. all operating details not specified in this document, or regarded as optional, together with details of any incidents which may have influenced the test result(s); +. any unusual features (anomalies) observed during the test; +. the date of the test. + +== Packaging + +The packaging shall not transmit any odour or flavour to the product and shall not contain substances which may damage the product or constitute a health risk. + +If bags are used, they shall comply with the requirements of <>, or <>, as appropriate. + +== Marking + +The packages shall be marked or labelled as required by the country of destination. + +[[AnnexA]] +[appendix,obligation=normative] +== Determination of defects + +=== Principle + +Extraneous matter, broken kernels, damaged kernels and other kinds of rice are separated manually according to the following types: husked rice, milled rice, husked parboiled rice and milled parboiled rice. Each type is then weighed. + +=== Apparatus + +The usual laboratory apparatus and, in particular, the following. + +[%inline-header] +[[AnnexA-2-1]] +==== Sample divider, + +consisting of a conical sample divider or multiple-slot sample divider with a distribution system, e.g. "Split-it-right" sample divider, such as that shown in <>. + +[%inline-header] +==== Sieve, + +with round perforations of diameter 1,4 mm. + +[%inline-header] +==== Tweezers. + +[%inline-header] +==== Scalpel. + +[%inline-header] +==== Paintbrush. + +[%inline-header] +[[AnnexA-2-6]] +==== Steel bowls, + +of diameter 100 mm ± 5 mm; seven per test sample. + +[%inline-header] +==== Balance, + +which can be read to the nearest 0,01 g. + +=== Sampling + +See <>. + +=== Procedure + +[[AnnexA-4-1]] +==== Preparation of test sample + +Carefully mix the laboratory sample to make it as uniform as possible, then proceed to reduce it, using a divider (<>), until a quantity of about 30 g is obtained. + +All parts of kernels which get stuck in the perforations of a sieve should be considered to be retained by the sieve. + +[[figureA-1]] +.Split-it-right sample divider +image:: images/a1.png[Alt1] + +=== Determination + +Weigh, to the nearest 0,1 g, one of the test samples obtained in accordance with <> and separate the different defects into the bowls (<>). When a kernel has several defects, classify it in the defect category for which the maximum permissible value is the lowest (see <>). + +Weigh, to the nearest 0,01 g, the fractions so obtained. + +=== Calculation + +Express the mass fraction of each defect using <>: + +[[formulaA-1,A.1]] +[stem] +++++ +w = (m_D) / (m_s) +++++ + +where + +stem:[w]:: is the mass fraction of grains with a particular defect in the test sample; +stem:[m_D]:: is the mass, in grams, of grains with that defect; +stem:[m_S]:: is the mass, in grams, of the test sample. + +=== Test report + +Report the results as specified in <>. + +[[AnnexB]] +[appendix,obligation=informative] +== Determination of the waxy rice content of parboiled rice + +=== Principle + +Waxy rice kernels have a reddish brown colour when stained in an iodine solution, while non-waxy rice kernels show a dark blue colour. + +=== Apparatus + +The usual laboratory apparatus and, in particular, the following. + +[%inline-header] +[[AnnexB-2-1]] +==== Balance, + +capable of weighing to the nearest 0,01 g. + +[%inline-header] +[[AnnexB-2-2]] +==== Glass beaker, + +of capacity 250 ml. + +[%inline-header] +[[AnnexB-2-3]] +==== Small white colour bowls, + +or any white colour container of a suitable size. + +[%inline-header] +[[AnnexB-2-4]] +==== Wire sieve, + +with long rounded apertures of (1 mm stem:[{:(+0.02),(0):}] mm) × (20 mm stem:[{:(+2),(-1):}] mm). + +[%inline-header] +[[AnnexB-2-5]] +==== Stirrer rod. + +[%inline-header] +[[AnnexB-2-6]] +==== Tweezers or forceps. + +[%inline-header] +[[AnnexB-2-7]] +==== Tissue paper. + +=== Reagents + +WARNING: Direct contact of iodine with skin can cause lesions so care should be taken in handling iodine. Iodine vapour is very irritating to eyes and mucous membranes. + +[%inline-header] +[[AnnexB-3-1]] +==== Deionized water, + +Grade 3 quality as specified in <>. + +[%inline-header] +[[AnnexB-3-2]] +==== Iodine stock solution, + +containing a mass fraction of 4,1 % iodine and 6,3 % potassium iodide in deionized water such as Lugols.footnote:[Lugols is an example of a suitable product available commercially. This information is given for the convenience of users of this document and does not constitute an endorsement by ISO of this product.] + +[%inline-header] +[[AnnexB-3-3]] +==== Iodine working solution, + +obtained by diluting the stock solution (<>) two times (by volume) with deionized water (<>). + +Prepare fresh daily. + +=== Sampling + +Sampling shall be carried out in accordance with <>. + +=== Determination + +==== {blank} +Weigh a portion of about 100 g of milled rice and put it into a glass beaker (<>). + +==== {blank} +Add enough iodine working solution (<>) to soak the kernels, and stir (<>) until all the kernels are submerged under the solution. Let the kernels soak in the solution for 30 s. + +==== {blank} +Pour the rice and solution into a wire sieve (<>), and shake the basket slightly in order to drain out the solution. Then place the wire sieve on a piece of tissue paper (<>) to absorb the excess liquid. + +==== {blank} +Pour the stained kernels into a bowl (<>). Using tweezers or forceps (<>), separate the reddish brown kernels of waxy rice from the dark blue kernels of non-waxy rice. + +==== {blank} +Weigh the waxy rice portion (stem:[m_1]) and the non-waxy rice portion (stem:[m_2]) to the nearest 0,1 g. + +=== Calculation + +Calculate the mass fraction, expressed as a percentage, of the waxy rice, stem:[w_(wax)], using <>: + +[[formulaB-1,B.1]] +[stem] +++++ +w_(wax) = (m_1) / (m_1 + m_2) xx 100 +++++ + +where + +stem:[m_1]:: is the mass, expressed in grams, of the waxy rice portion; +stem:[m_2]:: is the mass, expressed in grams, of the non-waxy rice portion. + +=== Test report + +Report the results as specified in <>, giving the results calculated using <>. + +[[AnnexC]] +[appendix,obligation=informative] +== Gelatinization + +<> gives an example of a typical gelatinization curve. <> shows the three stages of gelatinization. + +[[figureC-1]] +.Typical gelatinization curve +image::images/b1.png[Alt2] +footnote:[The time stem:[t_90] was estimated to be 18,2 min for this example.] + +*Key* + +stem:[w]:: mass fraction of gelatinized kernels, expressed in per cent +stem:[t]:: cooking time, expressed in minutes +stem:[t_90]:: time required to gelatinize 90 % of the kernels +P:: point of the curve corresponding to a cooking time of stem:[t_90] + +NOTE: These results are based on a study carried out on three different types of kernel. + +[[figureC-2]] +.Stages of gelatinization +==== +.Initial stages: No grains are fully gelatinized (ungelatinized starch granules are visible inside the kernels) +image::images/c2-a.png[Alt3] + +.Intermediate stages: Some fully gelatinized kernels are visible +image::images/c2-b.png[Alt4] + +.Final stages: All kernels are fully gelatinized +image::images/c2-c.png[Alt5] + +==== + +[[AnnexD]] +[appendix,obligation=informative] +== Results of interlaboratory test for husked rice yields + +An interlaboratory test <> was carried out by the ENR [Rice Research Centre (Italy)] in accordance with <> and <>, with the participation of 15 laboratories. Each laboratory carried out three determinations on four different types of kernel. The statistical results are shown in <>. + +[[tableD-1]] +[cols="<,^,^,^,^",headerrows=2] +.Repeatability and reproducibility of husked rice yield +|=== +.2+^| Description 4+| Rice sample +| Arborio | Drago footnote:[Parboiled rice.] | Balilla | Thaibonnet + +| Number of laboratories retained after eliminating outliers | 13 | 11 | 13 | 13 +| Mean value, g/100 g | 81,2 | 82,0 | 81,8 | 77,7 +| Standard deviation of repeatability, stem:[s_r], g/100 g | 0,41 | 0,15 | 0,31 | 0,53 +| Coefficient of variation of repeatability, % | 0,5 | 0,2 | 0,4 | 0,7 +| Repeatability limit, stem:[r] (= 2,83 stem:[s_r]) | 1,16 | 0,42 | 0,88 | 1,50 +| Standard deviation of reproducibility, stem:[s_R], g/100 g | 1,02 | 0,20 | 0,80 | 2,14 +| Coefficient of variation of reproducibility, % | 1,3 | 0,2 | 1,0 | 2,7 +| Reproducibility limit, stem:[R] (= 2,83 stem:[s_R]) | 2,89 | 0,57 | 2,26 | 6,06 +|=== + +[appendix,obligation=informative] +== Extraneous information + +_This appendix is not in the original Rice model document, and is inserted to illustrate elements absent from +that document: block quotes, source code, and examples._ + +[quote, ISO, "ISO7301,clause 1"] +_____ +This International Standard gives the minimum specifications for rice (_Oryza sativa_ L.) which is subject to international trade. It is applicable to the following types: husked rice and milled rice, parboiled or not, intended for direct human consumption. It is neither applicable to other products derived from rice, nor to waxy rice (glutinous rice). +_____ + +[%appendix] +=== Sample code + +[[samplecode]] +.Sample Code +==== + +[source,ruby] +-- +puts "Hello, world." +%w{a b c}.each do |x| <1> + puts x +end +-- +<1> This is an annotation +==== + + + +[bibliography] +== Bibliography + +* [[[ISO3696,ISO 3696]]], _Water for analytical laboratory use -- Specification and test methods_ + +* [[[ISO5725-1,ISO 5725-1]]], _Accuracy (trueness and precision) of measurement methods and results -- Part 1: General principles and definitions_ + +* [[[ISO5725-2,ISO 5725-2]]], _Accuracy (trueness and precision) of measurement methods and results -- Part 2: Basic method for the determination of repeatability and reproducibility of a standard measurement method_ + +* [[[ISO6322-1,ISO 6322-1]]], _Storage of cereals and pulses -- Part 1: General recommendations for the keeping of cereals_ + +* [[[ISO6322-2,ISO 6322-2]]], _Storage of cereals and pulses -- Part 2: Practical recommendations_ + +* [[[ISO6322-3,ISO 6322-3]]], _Storage of cereals and pulses -- Part 3: Control of attack by pests_ + +* [[[ISO7301,ISO 7301:2011]]], _Rice -- Specification_ + +* [[[ISO14864,ISO 14864:1998]]], _Rice -- Evaluation of gelatinization time of kernels during cooking_ + +* [[[IEC61010-2,IEC 61010-2:1998]]], _Safety requirements for electric equipment for measurement, control, and laboratory use -- Part 2: Particular requirements for laboratory equipment for the heating of material_ + +* [[[ref10,10]]] [smallcap]#Standard No I.C.C 167#. _Determination of the protein content in cereal and cereal products for food and animal feeding stuffs according to the Dumas combustion method_ (see http://www.icc.or.at) + +* [[[ref11,11]]] Nitrogen-ammonia-protein modified Kjeldahl method -- Titanium oxide and copper sulfate catalyst. _Official Methods and Recommended Practices of the AOCS_ (ed. Firestone, D.E.), AOCS Official Method Ba Ai 4-91, 1997, AOCS Press, Champaign, IL + +* [[[ref12,12]]] [smallcap]#Berner D.L., & Brown J.# Protein nitrogen combustion method collaborative study I. Comparison with Smalley total Kjeldahl nitrogen and combustion results. _J. Am. Oil Chem. Soc._ 1994, *71* (11) pp 1291-1293 + +* [[[ref13,13]]] [smallcap]#Buckee G.K.# Determination of total nitrogen in barley, malt and beer by Kjeldahl procedures and the Dumas combustion method -- Collaborative trial. _J. Inst. Brew._ 1994, *100* (2) pp 57-64 + +* [[[ref14,14]]] [smallcap]#Frister H.# _Direct determination of nitrogen content by Dumas analysis; Interlaboratory study on precision characteristics_. AOAC International, Europe Section 4th International Symposium, Nyon, Switzerland, 1994, 33 pp + +* [[[ref15,15]]] [smallcap]#Ranghino F.# Evaluation of rice resistance to cooking, based on the gelatinization time of kernels. _Il Riso_. 1966, *XV* pp 117-127 + +* [[[ref16,16]]] [smallcap]#Tkachuk R.# Nitrogen-to-protein conversion factors for cereals and oilseed meals. _Cereal Chem._ 1969, *46* (4) pp 419-423 diff --git a/tutorials/exercises_code/images/a1.png b/tutorials/exercises_code/images/a1.png new file mode 100644 index 00000000..afa1794a Binary files /dev/null and b/tutorials/exercises_code/images/a1.png differ diff --git a/tutorials/exercises_code/images/b1.png b/tutorials/exercises_code/images/b1.png new file mode 100644 index 00000000..8abda8ff Binary files /dev/null and b/tutorials/exercises_code/images/b1.png differ diff --git a/tutorials/exercises_code/images/c2-a.png b/tutorials/exercises_code/images/c2-a.png new file mode 100644 index 00000000..8cfbb3bd Binary files /dev/null and b/tutorials/exercises_code/images/c2-a.png differ diff --git a/tutorials/exercises_code/images/c2-b.png b/tutorials/exercises_code/images/c2-b.png new file mode 100644 index 00000000..b8ade44f Binary files /dev/null and b/tutorials/exercises_code/images/c2-b.png differ diff --git a/tutorials/exercises_code/images/c2-c.png b/tutorials/exercises_code/images/c2-c.png new file mode 100644 index 00000000..af26f565 Binary files /dev/null and b/tutorials/exercises_code/images/c2-c.png differ diff --git a/tutorials/learning_objectives.adoc b/tutorials/learning_objectives.adoc new file mode 100644 index 00000000..b9df6c51 --- /dev/null +++ b/tutorials/learning_objectives.adoc @@ -0,0 +1,30 @@ +== Learning objectives for the tutorials + +tag::learningobjectives-1[] +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 we will cover: + +* What Metanorma is +* 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 +end::learningobjectives-1[] + +tag::learningobjectives-2[] +Before we write our first Metanorma document, let us look at the foundation for all Metanorma documents: AsciiDoc. In this lesson, we will discuss what AsciiDoc is and what a typical Metanorma document looks like. You will also learn how to write AsciiDoc. +end::learningobjectives-2[] + +tag::learningobjectives-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: + +* How to add comments using AsciiDoc markup +* How to generate a draft using the command line. +end::learningobjectives-3[] + +tag::learningobjectives-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. +In this lesson you will learn: + +* How to generate PDF, HTML, and Word output using the command line +* How to troubleshoot common errors +end::learningobjectives-4[] \ No newline at end of file diff --git a/tutorials/template.html b/tutorials/template.html new file mode 100644 index 00000000..99b2ee27 --- /dev/null +++ b/tutorials/template.html @@ -0,0 +1,24 @@ + + + + + + +
+

In this lesson you will learn...

+

+ {% include content from another page%} + +

+ Sample code +
+
+ +
+
+ +
+ + + +--> Create a layout diff --git a/tutorials/tutorial_complete.adoc b/tutorials/tutorial_complete.adoc new file mode 100644 index 00000000..c21c6753 --- /dev/null +++ b/tutorials/tutorial_complete.adoc @@ -0,0 +1,396 @@ +//This file contains all the lessons for the tutorials. Since there was no template while Tina contributed to Metanorma, you'll find all lessons here, and you can copy the inlcudes into the tutorial templates later. +//All content that isn't fit for reuse elsewhere, for example the "Summary" sections, can be written into the file directly. +//Should you have any questions, you can contact me via e-mail (tina@kickoke.com). + +//Lesson 1 +== Introduction to Metanorma + +include::../tutorials/learning_objectives.adoc[tag=learningobjectives-1] +>> Start next lesson + +//Lesson 1-1 +== 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] +=== What is Metanorma? +include::../author/concepts/what_is_Metanorma.adoc[tag=tutorial] + +Let's explore the workflow of Metanorma in the next lesson. +>> Start next lesson + +//Lesson 1-2 +== The Metanorma Workflow + +include::../author/concepts/Metanorma_workflow.adoc[tag=tutorial, leveloffset=+1] + +Before we dive into AsciiDoc, let's summarize what we've covered so far. +>> Start next lesson + +//Lesson 1-3 +=== Summary + +Let's recap what we've learned so far: + +* Metanorma uses a what you see is what you mean (WYSIWYM) approach, meaning that the text you write is what you *want* to see. + +* 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 + +* 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. + +Now that we have covered the fundamentals, let's have a look at AsciiDoc. +>> Start next lesson + +//Lesson 2 +== Introduction to AsciiDoc + +include::../tutorials/learning_objectives.adoc[tag=learningobjectives-2] + +include::../author/concepts/intro_to_asciidoc.adoc[tag=tutorial, leveloffset=+2] + +We will have a look at these different levels of markup in the following lessons. + +You can do the exercises either in the browser, or on your local machine. If you choose to use your local machine, you will need to link:/install/[install Metanorma] and set up a new Metanorma project. + +>> Start next lesson + +//Lesson 2-1 +== The Header +include::../author/topics/metadata.adoc[tag=tutorial] + +[[exercise-2-1]] +include::../tutorials/exercises.adoc[tag=exercise-2-1] + + +Let's add some sections to our document in the next lesson. +>> Start next lesson + +//Lesson 2-2 +== Sections + +include::../author/topics/sections.adoc[tag=tutorial] + +[[exercise-2-2]] +include::../tutorials/exercises.adoc[tag=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. +>> Start next lesson + +//Lesson 2-3 +== Blocks +include::../author/topics/blocks.adoc[tag=tutorial] + +Let's look at lists in the next lesson. +>> Start next lesson + +//Lesson 2-3-1 +=== Lists + +include::../author/topics/blocks/lists.adoc[tags=tutorial,leveloffset=+2] + +[[exercise-2-3-1]] +include::../tutorials/exercises.adoc[tag=exercise-2-3-1] + +Great work! Let's have a look at term definitions in the next lesson. +>> Start next lesson + +//Lesson 2-3-2; Incorporate Tutorial content into author/topics/terms/ when reworking terms_definitions.adoc + +=== Term definitions +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] +---- +== Terms and definitions <1> + +=== husked rice <2> +deprecated:[cargo rice] <3> + +Paddy from which the husk only has been removed. <4> + +[.source] <5> +<>, The term "cargo rice" is shown as deprecated, and Note 1 to entry is not included here + +=== milled rice +alt:[white rice] <6> + +term:[husked rice] from which almost all of the bran and embryo have been removed by milling. <7> + +=== extraneous matter +alt:[EM] +domain:[rice] <8> + +organic and inorganic components other than whole or broken kernels + +[example] <9> +Foreign seeds, husks, bran, sand, dust. +---- +<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> The term `husked rice` supersedes `cargo rice`. To document the old term, use the annotation `deprecated:[term]`. +<4> Definition for the term: the first paragraph of text after macros like `deprecated:[]` and `alt:[]`. +<5> 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. +<6> `alt:[white rice]` indicates the alternative term for milled rice. +<7> `term:[husked rice]` cites the previously introduced term. +<8> Terms that do not obviously belong to a certain domain can be annotated with `domain:[]` at the start of their definition. +<9> If you provide an example, use the `[example]` attribute so that it renders according to the styling rules of your SDO. + + +[[exercise-2-3-2]] +include::../tutorials/exercises.adoc[tag=exercise-2-3-2] + +The next type of block we will cover are tables. +>> Start next lesson + +//Lesson 2-3-3 +=== Tables +include::../author/topics/blocks/tables.adoc[tag=tutorial] + +[[exercise-2-3-3]] +include::../tutorials/exercises.adoc[tag=exercise-2-3-3] + +Let's look at inserting images next. +>> Start next lesson + +//Lesson 2-3-4 +=== Images +include::../author/topics/blocks/images.adoc[tag=tutorial] + +[[exercise-2-3-4]] +include::../tutorials/exercises.adoc[tag=exercise-2-3-4] + +Let's look at admonitions next. +>> Start next lesson + +//Lesson 2-3-5 +=== Admonitions +include::../author/topics/blocks/admonitions.adoc[tag=tutorial,leveloffset=+2] +[[exercise-2-3-5]] +include::../tutorials/exercises.adoc[tag=exercise-2-3-5] + +Great progress so far! Let's look at code samples in the next lesson. +>> Start next lesson + +//Lesson 2-3-6 +=== Code Samples +// TODO: no code sample matched +// include::../author/topics/blocks/code_samples.adoc[tag=tutorial] +// [[exercise-2-3-6]] +include::../tutorials/exercises.adoc[tag=exercise-2-3-6] + +We're done with blocks - good job! The next lesson covers inline markup. +>> Start next lesson + +//Lesson 2-4 +== Inline Markup +include::../author/topics/inline_markup.adoc[tag=tutorial] + +Let's look at these features in the following lessons. +>> Start next lesson + +//Lesson 2-4-1 +=== Text markup +include::../author/topics/inline_markup/text_formatting.adoc[tag=tutorial,leveloffset=+2] +==== Footnotes +include::..//author/topics/inline_markup/footnotes.adoc[tag=tutorial] +[[exercise-2-4-1]] +include::../tutorials/exercises.adoc[tag=exercise-2-4-1] + +Let's look at a more advanced form of inline formatting: index entries +>> Start next lesson + +//Lesson 2-4-2 +=== Index Terms +include::../author/topics/inline_markup/index_terms.adoc[tag=tutorial] +[[exercise-2-4-2]] +include::../tutorials/exercises.adoc[tag=exercise-2-4-2] + +In the next lesson, we will cover references and links. +>> Start next lesson + +//Lesson 2-4-3 +=== References +include::../author/topics/inline_markup/links.adoc[tag=tutorial] +=== Bibliographic entries +include::../author/topics/sections/entering-bib.adoc[tag=tutorial] +[[exercise-2-4-3]] +include::../tutorials/exercises.adoc[tag=exercise-2-4-3] + + +Let's summarize what we've learnt so far. +>> Start next lesson + +//Lesson 2-4-4 +=== Summary + +We've covered a lot of ground, so here is a quick summary for you: + +* Each Metanorma document contains metadata in the header using the colon notation `:attribute:`. + +* 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]`) +** Metadata (`{attribute}`) +** Places in the document by setting an anchor (`[[anchor-id]]`) and referencing the anchor (`<>`) + +** 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. +>> Start next lesson + +//Lesson 3 +== Reviewing Metanorma Documents + +include::../tutorials/learning_objectives.adoc[tag=learningobjectives-3] + +>> Start next lesson + +//Lesson 3-1 +=== Adding Comments + +include::../author/topics/reviewing.adoc[leveloffset=1] + +[[exercise-3-1]] +include::../tutorials/exercises.adoc[tag=exercise-3-1] + +Now that we've commented on the content, let's create a draft of the document. +>> Start next lesson + +//Lesson 3-2 Add to docs +=== Rendering a Draft Document + +To render a draft that your peers should review, you need to add these metadata to the document header: + +* `:draft:`: Tells the compiler to display comments in the final output + +* `: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 command `metanorma` and the document you want to compile `document.adoc`. + +[source, shell] +---- +metanorma document.adoc +---- +With this command you trigger the Metanorma toolchain to: + +* Read the AsciiDoc input +* Convert it into XML +* Check the XML against the document model (XML schema) +* Create HTML, PDF, and DOC output + +[[exercise-3-2]] +include::../tutorials/exercises.adoc[tag=exercise-3-2] + + +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. +>> Start next lesson + +//Lesson 4 +== Publishing a Metanorma Document + +include::../tutorials/learning_objectives.adoc[tag=learningobjectives-4] + +>> Start next lesson + +//Lesson 4-1 +=== Compiling a Metanorma Document + +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. + +To compile a Metanorma document: + +. On the command line, go to the folder where the document you want to compile is located. +. Enter the following command: + +[source, shell] +---- +metanorma document.adoc +---- + +With this command you trigger the Metanorma toolchain to: + +* Read the AsciiDoc input +* Convert it into XML +* 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: + +.Example of a build command with a flag +[source, shell] +---- +metanorma document.adoc -x html +---- + +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. + +To see the full list of possible build commands, open the Metanorma help on the command line. + +[source, shell] +---- +metanorma help compile +---- + +>> Start next lesson + +// Lesson 4-2 +=== Troubleshooting +include::../author/topics/troubleshooting.adoc[tag=tutorial,leveloffset=+2] +include::../author/topics/troubleshooting.adoc[tag=no-compile-markup,leveloffset=+1] +include::../author/topics/troubleshooting.adoc[tag=rendering-errors,leveloffset=+1] + + +//Exercise will promt the user to fix some bugs in a document: For example syntax errors. +include::../tutorials/exercises.adoc[tag=exercise-4] +>> Start next lesson + +// Lesson 4-2 +=== Summary +Let's summarize what we've learnt in this lesson: + +* To generate a Metanorma document, enter the following command: + +[source, shell] +---- +metanorma document.adoc +---- + +* 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. +** 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! +>> Finish the tutorial +// Maybe include a page after the tutorial where a user can type in their name and a certificate (PDF) will be generated + downloaded? :)