README.adoc

About OGC Points of Interest (PoI) GitHub Repository

NOTICE: An analysis of alternatives for internationalized text is available for review and comment in HTML and PDF

This repository is the development space for the draft OGC Point of Interest (POI) Part 1: Conceptual Model Standard. Development of this Standard is taking place in the 21-049 directory. The current draft is available in HTML and PDF formats.

This Standard is accompanied by a Users Guide. Development of the Users Guide is taking place in the 22-053 directory. The current draft is available in HTML and PDF formats.

The draft OGC Point of Interest (POI) Part 2: JSON Encoding Standard defines how the POI Conceptual model should be implemented in JSON. Development of this Standard is taking place in the 23-045 directory. The current draft is available in HTML and PDF formats.

This repository also contains legacy files about and for the purpose of developing the PoI specification(s).

These files are from the following sources:

1. All contents of this repo beginning from when it was created by the transfer of work from the W3C to end of 2014 when the activity of the POI SWG stopped. These files were moved into a dedicated folder in order to preserve the prior work of the OGC POI SWG. At the same time as the files were put into their folder on this repo, all the issues created prior to the end of 2014 are labelled and closed.

2. OGC Templates GitHub Repository This is the origin of one file at the top level of this repo, the Draft PoI SWG charter template

3. A folder containing the template for the new POI draft specification.

Generating Documentation

OGC uses [Metanorma](https://www.metanorma.org) software for creating Standards documents.

You can compile documents using either a local installation of Metanorma or optionally a docker-containerized instance of Metanorma.

Using Metanorma from a local installation

Pre-requisite

Confirm that you have Metanorma installed locally on your operating system. If you do not have Metanorma installed, follow the steps at the [Metanorma website](https://www.metanorma.org/install/) to install it.

Getting the Templates

Step 1. Obtain the template for a Draft OGC Standard from the template sub-folder.

Editing a Draft OGC Standard for compilation with Metanorma

Now that you have obtained a copy of the template, you can edit the document. The following steps assume that you have read the authoring guidelines are at https://www.metanorma.org/author/ogc/authoring-guide/

Step 2. Next, edit the asciidoc file document.adoc by filling the document properties: docsubtype, status, abbrev, edition (i.e. version of the document), docnumber (OGC Document Number), keywords, fullname (of the editors).

Step 3. Ensure that the doctype property is set to standard.

Refer to the authoring guidelines for the complete list of document properties.

Note	If there are multiple editors, the names of the editors are listed in the sequence fullname, fullname_2, fullname_3,…​

Compiling a Draft OGC Standard with a local Metanorma instance

To convert the draft document from asciidoc format to HTML and PDF formats, we use the metanorma software to compile the document.

Step 4. From the folder containing the document.adoc file, run the following command.

metanorma compile --agree-to-terms -t ogc -x xml,html,doc document.adoc

Note	You need to add this option to retrieve licensed fonts --agree-to-terms

Using Metanorma from within Docker

Pre-requisite

Confirm that you have docker installed on your operating system. If you do not have docker installed, follow the steps at the [Get Docker page](https://docs.docker.com/get-docker/) to install it.

Creating a copy of the template

The template for Standards documents is organized as a folder of asciidoc files, with nested folders for sections, abstract tests, requirements and other resources.

To create a copy of the template, follow these steps.

Step 1. Pull the latest version of the Metanorma image on to your local docker installation.

docker pull metanorma/metanorma:latest

Step 2. Generate a copy of the template for OGC Standards by running the following command from a terminal (i.e. from the command prompt).

docker run --rm -v "$(pwd)":/metanorma metanorma/metanorma metanorma new -d standard -t ogc -l https://github.com/metanorma/metanorma-templates-ogc folder_for_standard

Note	The -d standard -t ogc flags instruct metanorma that the template is for OGC Standards.

Note	The folder_for_standard value can be replaced with whatever you would like to be the name of the folder that contains the copy of the template.

Editing a Draft OGC Standard for compilation with Metanorma

Now that you have generated a copy of the template, you can edit the document. The following steps assume that you have read the authoring guidelines are at https://www.metanorma.org/author/ogc/authoring-guide/

Step 3. Next, edit the asciidoc file document.adoc by filling the document properties: docsubtype, status, abbrev, edition (i.e. version of the standard), docnumber (OGC Document Number), keywords, fullname (of the editors).

Step 4. Ensure that the doctype property is set to standard.

Refer to the authoring guidelines for the complete list of document properties.

Note	If there are multiple editors, the names of the editors are listed in the sequence fullname, fullname_2, fullname_3,…​

Compiling a Draft OGC Standard with a docker-containerized Metanorma instance

To convert the draft standard from asciidoc format to HTML and PDF formats, we use the metanorma software to compile the document.

Step 5. From the folder containing the document.adoc file, run the following command.

docker run -v "$(pwd)":/metanorma -v ${HOME}/.fontist/fonts/:/config/fonts metanorma/metanorma metanorma compile --agree-to-terms -t ogc -x xml,html,doc document.adoc

Note	You need to add this option to retrieve licensed fonts --agree-to-terms