metanorma-iso 2.0.8.1 → 2.1.2

data/docs/quickstart.adoc

@@ -1,179 +0,0 @@
-= Quickstart Guide
-
-TIP: This guide has been authored for ISO standards, but most of it applies to all Metanorma standards. We indicate where guidance differs for different standards classes. See link:https://www.metanorma.com/software/Metanorma_processor/[List of Metanorma processors].
-
-This is a guide on how to get started using Metanorma to create documents aligned with different standards classes (such as ISO, GB, CSD, etc), in Microsoft Word and HTML formats. This guide is written to apply generically across the standards classes that can be expressed in Metanorma; guidance specific to a particular standards class is given as TIPs.
-
-Metanorma takes text in the _Asciidoctor markup language_ as input (consult the https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual] on the basics of this markup language).
-Metanorma makes some adjustments to the text format for its requirements;
-these adjustments (which we refer to as _Metanorma Asciidoctor_, or AsciiISO) are documented in relevant sections of this documentation.
-Metanorma uses Asciidoctor to generate _Metanorma XML_, as an intermediate, semantic representation of standards content.
-Metanorma XML in turn is processed by the https://github.com/metanorma/isodoc[isodoc] gem to generate output in Microsoft Word (`.doc`) and HTML (`.html`).
-
-== Even quicker summary
-
-In order to start a new Metanorma document, or migrate your document from Word:
-
-. Install <<installation>> (for your specific Metanorma standards class)
-. Clone the https://github.com/metanorma/isodoc-rice/[AsciiISO Rice]
-
-To migrate:
-
-. Use our https://github.com/metanorma/reverse_asciidoctor[reverse_asciidoctor] gem to help you convert a Word document into Asciidoctor. Be warned that the conversion will not be 100% clean, and you will have to manually fix some syntax (especially if your Word document contains an index, stray anchors, and equations).
-. Move the content back to the cloned isodoc-rice.
-. The isodoc-rice repository is set up for the ISO standards class; if you are not working with ISO, change its makefile to refer to the correct standards class (e.g. from `bundle exec metanorma -t iso -x doc,xml,html $^` to `bundle exec metanorma -t rsd -x doc,xml,html $^`
-
-[[supported-standards]]
-== Supported standards 
-
-
-As of this writing, Metanorma supports the following standards classes:
-
-* https://github.com/metanorma/metanorma-iso[ISO and IEC] (`iso`)
-* https://github.com/metanorma/metanorma-gb[Chinese National standards] (`gb`)
-* https://github.com/metanorma/metanorma-csd[Calconnect] (`csd`)
-* https://github.com/metanorma/metanorma-csand[Cloud Security Alliance] (`csand`)
-* https://github.com/metanorma/metanorma-m3d[Messaging, Malware and Mobile Anti-Abuse Working Group (M^3^AAWG)] (`m3d`)
-* https://github.com/metanorma/metanorma-rsd[Ribose] (`rsd`)
-* https://github.com/metanorma/metanorma-acme[Acme (shell for user-customised standards)] (`acme`)
-* https://github.com/metanorma/metanorma-mpfd[Mandatory Provident Fund Schemes Authority, Hong Kong (MPFA)] (`mpfd`)
-* https://github.com/metanorma/metanorma-unece[United Nations Economic Commission for Europe] (`unece`)
-
-== Installing on Linux and macOS
-
-Install Metanorma-ISO gem and its dependencies:
-
-You can install the metanorma-cli gem, and all its dependencies, through the Ruby gem installer:
-
-
-[source,console]
---
-gem install metanorma-cli
---
-
-If you want the latest version (note: may not be stable due to active development),
-you can install it from Github:
-
-[source,console]
---
-git clone https://github.com/metanorma/metanorma-cli.git
-cd metanorma-cli
-gem build *.gemspec
-gem install *.gem
-bundle update
---
-
-The final `bundle update` step updates the dependent gems, and is necessary because those gems are even more heavily under development.
-
-[TIP]
-====
-The Metanorma tool is a suite of https://en.wikipedia.org/wiki/RubyGems[Ruby gems], and works on the command line. The https://en.wikipedia.org/wiki/Ruby_programming_language[Ruby programming language] can be installed on Windows (e.g. https://rubyinstaller.org), but is typically run on a Unix command line—including Linux and MacOS. The following instructions are for the Unix console.
-
-The starting poing of the Metanorma tool is the `metanorma-cli` gem (command line interface); it references various other gems that the tool is based on, including the converter from Asciidoctor to Metanorma XML (`metanorma-standoc`), the converters from Metanorma XML to HTML and Word (`isodoc`, `html2doc`), the variants of Metanorma for different standards classes (`metanorma-iso`, `metanorma-csd`, etc.), and tools for processing bibliographies (`relaton`, `isobib` etc.)
-
-The Metanorma tools processing Asciidoctor, in turn, build on the https://asciidoctor.org[Asciidoctor gem], which interprets the Asciidoctor markup language in Ruby. Installing the Metanorma gem will install the Asciidoctor gem, if it is not already installed.
-
-Ruby comes with Linux and MacOS. Asciidoctor-ISO uses at minimum Ruby 2.3.0, and you may need to update your Ruby instance to use that version. Refer to https://www.ruby-lang.org/en/documentation/installation/
-====
-
-
-
-
-== Setting up a new project
-
-At its simplest, all you need is a text document in Asciidoctor-like AsciiISO format,
-which you compile using the Metanorma-ISO gem.
-
-To keep document dependencies in order, place your document in a distinct folder:
-
-
-[source,console]
---
-mkdir new_standard
-cd new_standard
-vi new_standard.adoc
---
-
-To compile the document, execute the `asciidoctor` script, flagging it to use a specific standards class with the `-t` flag (refer to <<stupported-standards>> for the abbreviations used); e.g.
-
-[source,console]
---
-metanorma -t iso new_standard.adoc
---
-
-This will generate two files from the `new_standard.adoc` document (provided it is well-formed):
-
-* `new_standard.html`, a standalone HTML document,
-* `new_standard.doc`, a Word document
-  (currently in the pre-2007 `.doc` format, but Microsoft Word will open it fine).
-
-Both these files are generated via an intermediate XML file, `new_standard.xml`, which represents the structure of the document as it is formally defined by the standards body, and captured in the https://github.com/metanorma/metanorma-model-iso[Metanorma XML schema].
-
-Even if there are no errors in the Asciidoctor syntax, the document may still raise warnings to the console as it is being validated. The validation comes from the formal definition of the standard class (e.g. ISO/IEC DIR 2 in the case of ISO and IEC), and consists of two parts: warnings about document content (e.g., for ISO, requiring space before a percentage sign; requiring that the scope not contain text that looks like a recommendation); and warnings about document structure. The latter are generated by running the generated XML against the ISOXML schema, and report the line numbers of the XML document where issues are observed.
-
-
-
-Even if there are no errors in the syntax, the document may still raise warnings
-to the console as it is being validated.
-The validation comes from ISO/IEC DIR 2, and consists of two parts:
-
-* Warnings about document content
-  (e.g., requiring space before a percentage sign,
-  or requiring that the scope not contain text that looks like a recommendation).
-* Warnings about document structure
-  (found from running the generated XML against the ISOXML schema,
-  they report the line numbers of the XML document where issues are observed).
-
-== Starting with an example project
-
-Perhaps the simplest way to get started is to take an existing Metanorma-ISO document
-and edit it, observing how it approaches various formatting tasks.
-
-The https://www.iso.org/publication/PUB100407.html["Rice document"]
-is the ISO's model document of an international standard.
-An Metanorma-ISO version of the document is available
-at https://github.com/metanorma/isodoc-rice/.
-We suggest downloading the site, and editing it.
-
-The `iso-rice-en.adoc` document consists of a document header,
-and it references the separate `body/body-en.adoc` document for the document proper (`include::body/body-en.adoc[]`).
-You can just continue on with the document text after the document header—so long as you remember to leave a blank line between the two.
-
-== Learning the AsciiDoc-based syntax
-
-To author AsciiDoc documents, you need to be familiar with the _core AsciiDoc syntax_,
-as well as _the syntax extensions and conventions_ that are specific to Metanorma-ISO.
-
-- Check out link:asciiiso-syntax[our AsciiISO syntax reference],
-  and link:guidance.adoc[Guidance for Authoring in Metanorma-ISO].
-
-- See also https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]
-  documenting Asciidoctor itself
-  and https://github.com/metanorma/metanorma-iso/blob/master/README.adoc[Metanorma-ISO README].
-
-== Migrating existing documents from Microsoft Word
-
-. Use our https://github.com/metanorma/reverse_asciidoctor[reverse_asciidoctor]
-gem to help you convert a Word document into AsciiISO.
-+
-You will likely have to manually clean up some syntax
-(especially if your Word document contains an index, stray anchors, and equations):
-don’t rely on the automatic conversion to be 100% correct.
-
-- Check out link:asciiiso-syntax[our AsciiISO syntax reference],
-  and link:guidance.adoc[Guidance for Authoring in Asciidoctor-ISO].
-
-- See also https://asciidoctor.org/docs/user-manual/[Asciidoctor User Manual]
-  documenting Asciidoctor itself
-  and https://github.com/metanorma/metanorma-iso/blob/master/README.adoc[Metanorma-ISO README].
-
-== Migrating existing documents from Microsoft Word:
-
-. Use our https://github.com/metanorma/reverse_asciidoctor[reverse_asciidoctor]
-  gem to help you convert a Word document into AsciiISO.
-
-  You will likely have to manually clean up some syntax
-  (especially if your Word document contains an index, stray anchors, and equations):
-  don’t rely on the automatic conversion to be 100% correct.
-. Move the content back to the cloned isodoc-rice.
-