Project PLATEAU sample documents

These documents belong to Project PLATEAU by MLIT.

Structure

sources/

source of the documents

sources/001-v4/

PLATEAU Handbook #01 source, v4.

sources/001-v4/iur/

i-UR data. Downloaded from here: https://www.chisou.go.jp/tiiki/toshisaisei/itoshisaisei/iur/index.html (see #128)

sources/002-v4/

PLATEAU Handbook #02 source, v4.

reference-docs/

Reference documents.

_site/

(automatically generated, in the gh-pages branch) published document.

collection.yml

The PLATEAU Handbook collection of 001 and 002. After compilation the output will be at index.html.

Usage (general)

Quick start

The easy way if you install locally:

git clone https://github.com/metanorma/mn-samples-plateau/
bundle
bundle exec metanorma sources/001-v4/document.adoc
# => sources/001-v4/document.{html,xml,pdf}

Installing Metanorma

See https://www.metanorma.org

Fetching the document

git clone https://github.com/metanorma/mn-samples-plateau/

Building a single document

bundle exec metanorma sources/001-v4/document.adoc # or whichever document

This command outputs the built document at:

• sources/001-v4/document.{html,pdf,xml}

Building the full site

bundle exec metanorma site generate

This command creates _site/. The HTML entry point is at _site/index.html.

Building the collection

Note	This functionality is experimental, it builds a site with split sections in HTML.

bundle exec metanorma collection collection.yml

This command creates _site/ with the HTML entry point at _site/index.html.

(DEPRECATED) Converting documents from HTML

Warning

There is NO NEED to convert the original HTML documents to Metanorma. This is only historic information, and the commands have already been changed.

Steps:

1. Install coradoc (run bundle install)

2. Obtain the index.html from https://www.mlit.go.jp/plateaudocument02/

3. Load the page entirely, and then copy/paste the HTML DOM content into a new index.html file.

4. Run the reverse_adoc command:

$ bundle exec reverse_adoc -rcoradoc/reverse_adoc/plugins/plateau --split-sections 2 --external-images -o sources/001-v4/document.adoc reference-docs/plateau-document-01-v4.html
$ bundle exec reverse_adoc -rcoradoc/reverse_adoc/plugins/plateau --split-sections 2 --external-images -o sources/002-v4/document.adoc reference-docs/plateau-document-02-v4.html

Where:

reference-docs/plateau-document-01.html

is the input document

-o plateau-document-01/index.adoc

is the output document path

--split-sections

means to split files at Clause level 2

--external-images

means to extract out all images to separate files

-rcoradoc/reverse_adoc/plugins/plateau

applies Plateau-specific conversions

Editor usage

Convert images from webp to PNG

Some PLATEAU documents utilize webp images.

Due to #7 , the PDF renderer we use, Apache FOP, does not support webp images.

Hence at import we have to convert all webp images into PNG.

Converting with parallel processing: (if you have GNU Parallel)

$ parallel dwebp {} -o {}.png ::: *.webp

Converting sequentially:

$ find . -name "*.webp" -exec dwebp \{} -o \{}.png

Updating the files to refer to the new .png files:

sed -i '' 's/\.webp/.webp.png/g' sources/001-v3/sections/*.adoc

Running via Docker or locally

If you have installed the build tools locally, and wish to run the locally-installed compilation tools, there is nothing further to set.

If you don’t want to deal with local dependencies, use the docker:

docker run -v "$(pwd)":/metanorma -w /metanorma -it metanorma/metanorma metanorma site generate

Building a Firelight deliverable using containers

This example assumes:

• You are building document PLATEAU 01.

• You want to build without the /plateaudocument/ path prefix as used in Plateau production deployment environment.

• You use Bash shell and are in the same directory as repository root.

• You executed the command metanorma sources/001-v5/document.adoc beforehand.

• You want Firelight output to be in an existing subdirectory firelight-build-001.

First, create a config file with this command. (Do not add this file in Git, it will only be used for local build and can be deleted any time later.)

cat <<'EOF' > anafero-config.json
{
  "version": "0.1",
  "entryPoint": "file:documents/001-v5/document.presentation.xml",
  "storeAdapters": [
    "git+https://github.com/metanorma/firelight#main/packages/metanorma-xml-store"
  ],
  "contentAdapters": [
    "git+https://github.com/metanorma/firelight#main/packages/metanorma-site-content"
  ],
  "resourceLayouts": [
    "git+https://github.com/metanorma/firelight#main/packages/plateau-layout"
  ]
}
EOF

Then, instruct Docker to run a Firelight build NPX command in a Node container as follows.

docker --log-level=debug run --interactive --tty \
-v .:/data:ro -v ./firelight-build-001:/out:rw \
--workdir=/data \
docker.io/library/node:22-alpine \
  npx --node-options='--experimental-vm-modules' -y @riboseinc/anafero-cli \
    build-site --target-dir /out --current-rev master

Now, you can navigate to build output directory and run a local webserver.

cd firelight-build-001
python3 -m http.server 8888

Now you should be able to open localhost:8888 in your browser and see the document.