metanorma / basicdoc-models Goto Github PK

The BasicDoc model

Makefile 47.54% Shell 40.63% Ruby 11.83%

basicdoc-models's Introduction

Metanorma: the standard for standards

Metanorma is dedicated to harmonizing standard documents produced by different standard-setting bodies in a manner that maintains correct semantics while allowing each standard publisher to define appropriate semantic extensions.

Simply put, it allows standards bodies or any other organization to create their own standard or specification document in a best practices manner.

Metanorma is composed of a number of specifications and software implementations. The Metanorma document model is based on the SecureDoc document model.

For more on Metanorma and who uses it, refer to https://www.metanorma.org

Installation on supported platforms

See https://www.metanorma.org/install/

Installing individual components

The Metanorma workflow can be utilized via the metanorma-cli Ruby gem.

gem install metanorma-cli

Usage

Refer to Metanorma man page and Metanorma usage

Threaded execution

Metanorma has threaded execution, to generate output documents from the same Presentation XML input more quickly. Similar to relaton, the METANORMA_PARALLEL environment variable can be used to override the default number of parallel fetches used.

Origin of name

Meta- is a prefix of Greek origin ("μετα") for “with” “after”. In English, it has ended up meaning "about (its own category)"; e.g. meta-discussion (a discussion about discussion). (For the roundabout way it ended up with that meaning, see https://en.wikipedia.org/wiki/Meta#Etymology.)

Norma is Latin for “rule” and “standard”; hence English norm, but also German Norm "standard".

The Metanorma project is for setting a standard for standard documents created by standards-setting organizations (which is a meta thing to do); hence this name.

Metanorma seeks to embrace all standards documents standards, but not possess any: it can give rise to many "standard" standards, but not limit the extension of any of those standards.

The motto of the project is Aequitate verum, "Truth through equity". Dealing with all standards fairly (aequitate), we seek not an abstract virtue (veritas), but a practical reality on the ground (verum), that can be used by stakeholders of multiple standards.

basicdoc-models's People

Contributors

Stargazers

Watchers

Forkers

freight-trust

basicdoc-models's Issues

Review Change models

We need a deeper review of the Change models to match our existing implementation.

I think at least the NodeMove/Insert actions needs to accept a single RefNode with a RefPosition to know where exactly to insert a node.

cc: @PeterTKY @ribose-jeffreylau

Create Change model to represent changes on BasicDoc

Relax paragraph ID presence

We need p[@id] in paragraph-with-footnote to be optional. The paragraph-with-footnote used in the abstract and we convert RFC's <t> to <p> without ID.

version/version => version/draft

At some time in the past few months, we had agreed to rename version/version to version/draft. Please confirm that's still the case; I will need to change the published diagrams here.

Document BasicDoc

We should describe the BasicDoc structure using a RSD document here, and integrate the model images into the RSD document using the provided PlantUML files ("Source Files")

Split off Basic Doc RNC

Currently the isodoc.rnc in metanorma-model-iso contains both BasicDoc and StanDoc. The BasicDoc component of the grammar is to be split off from isodoc.rnc, and moved here as basicdoc.rnc; isodoc.rnc is to inherit that grammar through a submodule.

Convert BasicDoc models into LutaML

@w00lf can you help with this? Thanks!

Review of the basicdoc models

Аll models need to be revised and updated according the diagrams posted to the home page of this repo.

Expansion in scope of notes

Until now, notes have been restricted to being runs of paragraphs, and they can appear attached underneath any other block.

Recent feedback obtained by ISO is that notes and examples should be treated the same, as containing any number of different blocks, including:

formulas
paragraphs
tables (without borders)
numbered/unnumbered bullet lists and sub-lists
indented text
graphics

As it happens, the Asciidoctor format will permit this kind of embedding in its multi-block notes, so notes looking like that will be converted successfully into XML. However there is no provision in the Metanorma grammar for this, and there is no provision in rendering.

Taking account of such notes will generate a lot of work, which must not be underestimated, and it cannot proceed until the following questions are resolved.

Are heterogeneous notes a characteristic of basicdoc, standoc, or specifically ISO?
Are embedded notes within tables, terms, admonitions, figures, lists also heterogeneous, or constrained to be paragraphs? (In this instance, Asciidoctor constrains what is possible; but there are good reasons why such structures are undesirable.)
How are these heterogeneous notes to be rendered visually, so as to make them identifiable as a unit? Note that while HTML rendering in Metanorma visually codes them with a background colour, Word rendering currently uses only font size, and has foregone indentation.
How are the embedded blocks to be rendered differently? It has been suggested for example that tables are to be rendered without borders.
How are the embedded blocks to be referenced? One alternative is not to reference them differently from their container, as a note. If they are to be referenced differently, the referencing code may end up complex (Section 823, Note 4, Table 2?)