metanorma-tools 0.1.0

data/docs/iso-drg-filename-guidance.adoc

@@ -0,0 +1,584 @@
+= ISO DRG compliance
+
+== Overview
+
+=== General
+
+The ISO DRG (Document Review Group) requirements for document processing are
+specified in the "DRG working instructions and directives" (August 2020), 3.1
+"Revisable files".
+
+3.1 provides a quote on their guidelines for submission:
+
+[quote]
+____
+Guidelines for the submission of text and graphics to ISO/CS (2020)
+
+As a general rule, submitted graphic files (e.g. diagrams, technical drawings)
+need to be revisable and language neutral (with the exception of flowcharts and
+organigrams). All drawing elements within the graphics (lines, symbols, etc.)
+must be modifiable, allowing ISO/CS to adjust or change them when necessary
+during the editing process. All text elements must be editable, and not
+pixelized or outlined text. In addition, the revisable graphic files are made
+available to the ISO members for their publishing activities.
+
+To this end, please submit revisable (vector-drawn) files. ISO/CS is not
+responsible for redrafting graphics that are not revisable.
+
+ISO/CS recommends the formats listed below:
+
+* AutoCAD (.dwg or .dxf)
+* Illustrator (.ai)
+* Vector file type (.eps or .svg)
+* Word (.doc .docx), Excel (.xls .xlsx), Powerpoint (.ppt .pptx), Visio (.vsd .vsdx)
+* CorelDraw (.cdr)
+
+The following formats may be used only for images, pictures, etc. where there
+are no text elements:
+
+* .png, .tif, .jpeg
+____
+
+The actual naming convention is as follows.
+
+== File naming convention
+
+=== General
+
+The file naming requirements differ by document type.
+
+In 3.2 "File names" two file name patterns are given but they are not
+complete as these components are missing:
+
+* subfigure (described in the block image and examples);
+* key (described in the block image and examples);
+* language (described in the block image and examples);
+* development stages (not described).
+
+Here we provide a complete pattern for the ease of understanding
+and example listing.
+
+There are four parts of the full filename pattern:
+
+* document portion
+* in-document portion
+* language portion
+* file extension portion
+
+== Document portion
+
+=== For Standard, TS, TR, PAS, IWA
+
+[source]
+----
+{StandardNumber}[-{partNumber}][_{stageCode}]_ed{editionNumber}
+----
+
+Where:
+
+`StandardNumber`::
+The standard number, e.g. `12345`
+
+`partNumber`::
+The part number, e.g. `1`
+
+`stageCode`::
+The stage code, one of: `pwi`, `np`, `awi`, `wd`, `cd`, `dis`, `fdis`, `prf`
+(final stage uses empty code)
+
+`editionNumber`::
+The edition number, e.g. `1`
+
+[example]
+====
+For the first edition of ISO 12345-1, the document portion is
+`12345-1_ed1`.
+====
+
+NOTE: TR/TS do not use the codes "FDIS" etc. TODO ask ISO/CS what the proper
+codes are.
+
+NOTE: The development stage is also provided.
+
+=== For Amendments / Corrigenda
+
+[source]
+----
+{StandardNumber}-{partNumber}[_{stageCode}]_ed{editionNumber}{supplementCode}{supplementNumber}
+----
+
+Where:
+
+`StandardNumber`::
+The standard number, e.g. `12345`
+
+`partNumber`::
+The part number, e.g. `1`
+
+`stageCode`::
+The stage code, one of: `pwi`, `np`, `awi`, `wd`, `cd`, `dis`, `fdis`, `prf`
+(final stage uses empty code)
+
+`editionNumber`::
+The edition number, e.g. `1`
+
+`supplementCode`::
+The supplement code. One of `amd`, `cor`
+
+`supplementNumber`::
+The supplement number, e.g. `1`
+
+[example]
+====
+For the second amendment to the first edition of ISO 12345-2, the portion is
+`12345-2_ed1amd2`.
+
+For the second amendment at FDAM to the first edition of ISO 12345-2, the
+portion is `12345-2_ed1amd2_fdis`.
+====
+
+NOTE: Amendments do not use the codes "FDIS" etc. TODO ask ISO/CS what the
+proper codes are.
+
+NOTE: The development stage is also provided.
+
+== In-document portion
+
+=== General
+
+There are 3 types of in-document types:
+
+=== Figure and subfigure
+
+Where `subfigureAlphabet` is in lower alphabetic characters:
+
+[source]
+----
+fig{figureNumber}[subfigureAlphabet][_{languageCode}]
+----
+
+[example]
+====
+* "Figure 3" is represented as `fig3`.
+* Figure 3 in French is represented as `fig3_f`.
+* "Figure 3 a)" is represented as `fig3a`.
+* "Figure 3 a)" in French is represented as `fig3a_f`.
+* "Figure A.2" is represented as `figA2`.
+====
+
+=== Table
+
+Where `tableNumber` is in lower alphabetic characters:
+
+[source]
+----
+{figurePortion}Tab{tableNumber}
+----
+
+[example]
+====
+* "Table 3" is `figTab3`.
+* Second figure in "Table 1": `figTab1b`. (TODO Is this unnumbered?)
+====
+
+=== Figure key
+
+Representing an individual key as legend to the figure:
+
+[source]
+----
+{figurePortion}_key{keyNumber}
+----
+
+[example]
+====
+Second key in "Figure 1": `fig1_key2`
+====
+
+=== Inline image in text
+
+Where `textNumber` is in lower alphabetic characters:
+
+[source]
+----
+figText{textNumber}
+----
+
+[example]
+====
+* First graphical element inline with text: `figText1`
+* Third graphical element inline with text: `figText3`
+====
+
+NOTE: There is also description of the "Special Layout" with such a pattern:
+"File for table 1 which does not have a figure number" is assigned the file
+name `SL12345-1_ed1figTab1.dwg`. Since I have no idea what the special layout
+is and is likely rare to encounter, it is omitted from this.
+
+== Language portion
+
+=== General
+
+Valid entries are:
+
+`_e`::
+English, but it is no longer needed
+
+`_f`::
+French
+
+`_r`::
+Russian
+
+`_s`::
+Spanish
+
+`_a`::
+Arabic
+
+`_d`::
+German
+
+== Original filename preservation
+
+=== General
+
+When extracting figures from Metanorma documents, if the original image has a
+`filename` attribute, the ISO DRG pattern is extended to preserve the original
+filename:
+
+[source]
+----
+{isoDRGpattern}_{originalFilename}.{extension}
+----
+
+Where:
+
+`isoDRGpattern`::
+The standard ISO DRG filename pattern as described above
+
+`originalFilename`::
+The original filename (without extension) from the `filename` attribute
+
+`extension`::
+The file extension
+
+[example]
+====
+For Figure 1 with original filename "diagram-overview.png":
+`12345-1_ed1fig1_diagram-overview.png`
+
+For Figure A.2 subfigure a with original filename "flowchart.svg":
+`12345-1_ed1figA2a_flowchart.svg`
+====
+
+This extended pattern ensures that:
+
+. Files follow ISO DRG naming conventions for proper document management
+. Original filenames are preserved for reference and traceability
+. The relationship between extracted figures and source documents is maintained
+
+== File extension portion
+
+=== General
+
+ISO/CS (pretty much) only accepts these files.
+
+=== Vector formats
+
+* AutoCAD (`.dwg` or `.dxf`)
+* Illustrator (`.ai`)
+* Vector file type (`.eps` or `.svg`)
+* Word (`.doc`, `.docx`), Excel (`.xls`, `.xlsx`), Powerpoint (`.ppt`, `.pptx`),
+  Visio (`.vsd`, `.vsdx`)
+* CorelDraw (`.cdr`)
+
+=== Raster formats
+
+Only useable when no text:
+
+* Portable Network Graphics (`.png`)
+* Tagged Image File Format (`.tif`)
+* Joint Photographic Experts Group (`.jpeg`)
+
+== Examples
+
+=== General
+
+The following examples are given by the source document.
+
+.File naming examples from ISO DRG Section 3.2
+[cols="1,2,3",options="header"]
+|===
+| Where used | Filename | Description
+
+| Normal figure
+| `12345-1_ed1fig1.dwg`
+| File for figure 1
+
+| Normal figure
+| `12345-1_ed1fig2.dwg`
+| File for figure 2
+
+| Normal figure, subfigure
+| `12345-1_ed1fig1a.dwg`
+| File for figure 1, subfigure a
+
+| Normal figure, subfigure
+| `12345-1_ed1fig1b.dwg`
+| File for figure 1, subfigure b
+
+| Normal figure, key file
+| `12345-1_ed1fig1_key1.dwg`
+| File for figure 1, first key file
+
+| Normal figure, key file
+| `12345-1_ed1fig1_key2.dwg`
+| File for figure 1, second key file
+
+| Table
+| `12345-1_ed1figTab1.dwg`
+| File for the single figure in Table 1
+
+| Table
+| `12345-1_ed1figTab1a.dwg`
+| File for the first figure in Table 1
+
+| Table
+| `12345-1_ed1figTab1b.dwg`
+| File for the second figure in Table 1
+
+| Annex
+| `12345-1_ed1figA1.dwg`
+| File for the first figure in appendix A
+
+| Annex
+| `12345-1_ed1figA2.dwg`
+| File for the second figure in appendix A
+
+| Annex
+| `12345-1_ed1figA1a.dwg`
+| File for first figure in appendix A, subfigure a
+
+| Annex
+| `12345-1_ed1figA1b.dwg`
+| File for first figure in appendix A, subfigure b
+
+| Language
+| `12345-1_ed1fig1_f.dwg`
+| File for figure 1, French translation
+
+| Amendment
+| `12345-1_ed1amd1fig1.dwg`
+| File for figure 1 of amendment 1
+
+| Inline
+| `12345-1_ed1figText1.dwg`
+| File for graphical element inline with text
+
+| Special Layout
+| `SL12345-1_ed1figTab1.dwg`
+| File for table 1 which does not have a figure
+|===
+
+== Data structure
+
+=== General
+
+The data structure is designed to be MECE (Mutually Exclusive, Collectively
+Exhaustive) and covers all ISO DRG filename patterns.
+
+=== Core schema
+
+[source,yaml]
+----
+# Document identification (required)
+standard_number: 12345        # ISO standard number
+part_number: 1                # optional, part number
+edition_number: 2             # edition number
+
+# Development stage (optional)
+stage_code: "fdis"            # pwi|np|awi|wd|cd|dis|fdis|prf or empty for final
+
+# Supplement information (for amendments/corrigenda only)
+supplement_type: "amd"        # amd|cor (optional)
+supplement_number: 1          # required if supplement_type present
+
+# Content type (required - mutually exclusive)
+content_type: "figure"        # figure|table|key|text|special_layout
+
+# Content-specific fields (conditional based on content_type)
+figure_number: "3"            # required for figure|table|key types
+subfigure: "a"                # optional, single lowercase letter (figure only)
+table_number: "1"             # used for table content_type
+key_number: 2                 # required for key content_type
+text_number: 1                # required for text content_type
+
+# Localization (optional)
+language_code: "f"            # e|f|r|s|a|d (empty for English)
+
+# Output format (required)
+file_extension: "svg"         # svg|dwg|ai|eps|png|tif|jpeg|etc.
+----
+
+=== Field validation rules
+
+* `standard_number`: Required integer
+* `part_number`: Optional integer
+* `edition_number`: Required integer
+* `stage_code`: Optional string, one of: `pwi`, `np`, `awi`, `wd`, `cd`, `dis`,
+  `fdis`, `prf`, or empty for final stage
+* `supplement_type`: Optional string, one of: `amd`, `cor`
+* `supplement_number`: Required integer if `supplement_type` is present
+* `content_type`: Required string, one of: `figure`, `table`, `key`, `text`,
+  `special_layout`
+* `figure_number`: Required for `figure`, `table`, `key` content types. Format:
+  number or letter+number (e.g., "3", "A.2")
+* `subfigure`: Optional single lowercase letter (a-z), only valid for `figure`
+  content type
+* `table_number`: Used for `table` content type, typically same as
+  `figure_number`
+* `key_number`: Required integer for `key` content type
+* `text_number`: Required integer for `text` content type
+* `language_code`: Optional string, one of: `e`, `f`, `r`, `s`, `a`, `d`
+* `file_extension`: Required string
+
+=== Content type examples
+
+==== Standard figure
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "figure"
+figure_number: "3"
+file_extension: "svg"
+# Generates: 12345-1_ed2fig3.svg
+----
+
+==== Figure with subfigure
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "figure"
+figure_number: "3"
+subfigure: "a"
+file_extension: "svg"
+# Generates: 12345-1_ed2fig3a.svg
+----
+
+==== Table figure
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "table"
+figure_number: "1"
+table_number: "1"
+file_extension: "svg"
+# Generates: 12345-1_ed2figTab1.svg
+----
+
+==== Figure key
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "key"
+figure_number: "1"
+key_number: 2
+file_extension: "svg"
+# Generates: 12345-1_ed2fig1_key2.svg
+----
+
+==== Inline text graphic
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "text"
+text_number: 1
+file_extension: "svg"
+# Generates: 12345-1_ed2figText1.svg
+----
+
+==== Amendment figure
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+supplement_type: "amd"
+supplement_number: 1
+content_type: "figure"
+figure_number: "3"
+file_extension: "svg"
+# Generates: 12345-1_ed2amd1fig3.svg
+----
+
+==== Figure with language
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "figure"
+figure_number: "3"
+language_code: "f"
+file_extension: "svg"
+# Generates: 12345-1_ed2fig3_f.svg
+----
+
+==== Annex figure
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "figure"
+figure_number: "A.2"
+file_extension: "svg"
+# Generates: 12345-1_ed2figA2.svg
+----
+
+==== Development stage figure
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+stage_code: "fdis"
+content_type: "figure"
+figure_number: "3"
+file_extension: "svg"
+# Generates: 12345-1_fdis_ed2fig3.svg
+----
+
+==== Special layout
+
+[source,yaml]
+----
+standard_number: 12345
+part_number: 1
+edition_number: 2
+content_type: "special_layout"
+figure_number: "1"
+table_number: "1"
+file_extension: "dwg"
+# Generates: SL12345-1_ed2figTab1.dwg
+----

data/docs/workflows-iso.adoc

@@ -0,0 +1,70 @@
+= ISO workflows with Metanorma Tools
+
+== Purpose
+
+This document provides guidance on using Metanorma Tools for ISO-specific
+standards editing workflows.
+
+Metanorma Tools supports the complete ISO standards editing lifecycle, from
+document preparation through comment resolution and final publication. The
+tools are designed to work with ISO's specific requirements and processes.
+
+== Workflow
+
+A project leader is required to perform these actions in the development of
+an ISO document:
+
+Step 1: Import the ISO source document into Metanorma from:
+
+* from a Word file from ISO/CS;
+* from a Word file from the Committee Secretariat;
+* from an ISO STS / NISO STS XML file from ISO/CS;
+* ... if all else fails we import at least the terms from the ISO OBP.
+
+
+Step 2: Iterate the Metanorma ISO document stage by stage and balloting between stages
+
+* progressing through stages PWI/NP/AWI/WD/WDS/CD/CDS/D[IS|TR|TS|AM|COR]/FD[IS|TR|TS|AM|COR]/PRF;
+* iterate the document, update attributes of `stage`, `substage`, `revdate`, `vote-date-*`;
+* create study review / ballot packages
+** provide a Word file
+** provide a PDF file
+** at DIS / FDIS / PRF / IS, provide the DIS Word templated document to ISO/CS
+** (this gem does this now!) provide a figure package
+* at each stage, manage comments on the ISO commenting template synchronizing with the chosen issue system (e.g. GitHub Issues)
+* at each stage, port commented changes back to the Metanorma source
+* after comments are resolved, link the commits/PRs to the comment IDs
+* upload package to the chosen CI/CD release platform (e.g. GitHub Releases) and mark milestone
+
+Step 3: Enjoy the publication!
+
+== Figure package and extraction
+
+Extract a figure package with compliant ISO DRG filenames:
+
+[source,shell]
+----
+$ metanorma-tools extract-images iso-document.presentation.xml --zip
+# From ISO 690 edition 3
+# => 690_ed3.zip (with figures 690_ed3figX.svg)
+# From ISO/FDIS 19135 edition 2
+# => 19135_fdis_ed2.zip (with figures 19135_fdis_ed2figX.svg)
+----
+
+Details at: link:figure-extraction.adoc[Figure extraction]
+
+// Planned: Import ISO comment sheets:
+
+// [source,shell]
+// ----
+// $ metanorma-tools comment import "ISO DIS comments.docx" --output comments.yaml
+// ----
+
+// Planned: Fetch ISO documents from OBP:
+
+// [source,shell]
+// ----
+// $ metanorma-tools obp-import urn:iso:80000:2:2019:en
+// ----
+// ====
+

data/exe/metanorma-tools

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/metanorma/tools"
+
+Metanorma::Tools::Cli.start(ARGV)