Merge pull request #720 from metanorma/doc20230606

PR of all updates since November 2022

.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

.lycheeignore

@@ -5,4 +5,8 @@ https://twitter.com/RiboseUS
 .*@viagenie.ca
 .*@.*example.com
 (ht|f)tps?://.*\.?example\.(com|org).*
-ldap://.*
+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/

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

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<uppercase flavor abbreviation>`.
@@ -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 <organization abbreviation> <documents|standards> with Metanorma
   data_models: <specs entry>
 
   # (optional)
-  # Use for “experimental” flavors not ready for production.
+  # Use for "experimental" flavors not ready for production.
   experimental: yes
 
 ----

_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:

_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:

_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 }}

_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:

_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