Community Standard and Discussion Paper possibly missing from document categories

[ghobona]

Community Standard and Discussion Paper might be missing from the Category list in standard_document.adoc

[tomkralidis]

cc @solson-nws @ShaneMill1 @m-burgoyne

@ghobona @gbuehler: as part of MetOceanDWG activities we are beginning work on a discussion paper for PubSub. It looks like this document setup is for a specification (normative clauses, etc.).

Looking at current discussion papers (https://docs.ogc.org/dp/19-047.html, https://docs.ogc.org/dp/21-067.html), where can we find a similar template for a DP?

[ghobona]

@tomkralidis All OGC Documents, including Discussion Papers, now use the metanorma-ogc templates.

Below are the instructions for generating the template. A version of the instructions is in a README.md.

The template for Discussion Paper documents is organized as a folder of asciidoc files, with nested folders for sections, 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 Discussion Paper documents by running the following command from a terminal (i.e. from the command prompt).

docker run -v "$(pwd)":/metanorma metanorma/metanorma metanorma new -d discussion-paper -t ogc -l https://github.com/metanorma/metanorma-templates-ogc folder_for_discussion_paper

NOTE: The -d discussion-paper -t ogc flags instruct metanorma that the template is for OGC Discussion Paper documents.

NOTE: The folder_for_discussion_paper 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 Discussion Paper document 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: status, abbrev, edition (i.e. version of the document), docnumber (OGC Document Number), keywords, fullname (of the editors).

Step 4. Ensure that the doctype property is set to discussion-paper.

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 Discussion Paper document with a docker-containerized Metanorma instance

To convert the draft OGC Discussion Paper 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

[tomkralidis]

Thanks @ghobona. OK, so this is exactly what's been done by @solson-nws already, great!

1. I think this area of the README needs to be updated? https://github.com/opengeospatial/templates/blob/master/discussion_paper/README.md#getting-the-templates
2. Is it common for a discussion paper to have normative clauses? We would like to put forth a DP with the core/critical path concepts as proposals, which would then (hopefully) lead to a specification development activity (which has normative clauses, of course) as next steps (looking at https://docs.ogc.org/dp/19-047.html#_metadata_profiles as an example).

[ghobona]

@tomkralidis

Response to Q1: Which part of the README needs to be updated?

Response to Q2: Some discussion papers (e.g. OGC 21-077 and OGC 16-114r2) do have normative clauses such as requirements classes and requirements.

[tomkralidis]

Q1: in https://github.com/opengeospatial/templates/blob/master/discussion_paper/README.md#getting-the-templates :

Step 1. Obtain the template for a Draft OGC Discussion Paper document from the template sub-folder.

In templates/discussion_paper, there no sub-folder called template ?