Open ghobona opened 6 years ago
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?
@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.
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
,...
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
Thanks @ghobona. OK, so this is exactly what's been done by @solson-nws already, great!
@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.
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
?
Community Standard and Discussion Paper might be missing from the Category list in standard_document.adoc