search

opengeospatial / ogcapi-common

OGC API - Common provides those elements shared by most or all of the OGC API standards to ensure consistency across the family.
https://ogcapi.ogc.org/common
Other
45 stars 14 forks source link

Conversion of part 1 to metanorma asciidoc #316

Closed ghobona closed 1 year ago

ghobona commented 2 years ago

This pull request contains changes that convert OGC API - Common - Part 1 to metanorma asciidoc.

cmheazel commented 2 years ago

This branch still needs some work: 1) The Scope and Conformance sections are swapped in the PDF rendering 2) The table of contents of the Word rendering includes the copyright notice and license agreement 3) Twelve "Hanging paragraph in clause" errors reported by Metanorma 4) Five XML syntax errors reported by Metanorma I have fixed a number of other errors, but I will need some help on these four.

Note: I am also moving POI and API-Coverages to Metanorma. I'm having similar issues with these repositories.

cmheazel commented 2 years ago

Question - Other repositories use the document number to identify the directory where the asciidoc files reside and also as the file name of the generated documentation. Should we convert API-Common to follow this pattern? (I vote yes).

ghobona commented 2 years ago

@cmheazel We generally ignore the "Hanging paragraph in clause" error messages because they do not affect the HTML and PDF rendering. Similarly with the Metanorma XML Syntax, they relate to the metanorma XML document - which we do not publish. We only publish HTML and PDF documents.

ghobona commented 2 years ago

@cmheazel Thanks for spotting the swapped sections. I have just raised a ticket (https://github.com/metanorma/metanorma-ogc/issues/403) for the attention of @ronaldtse.

cmheazel commented 2 years ago

Question - should requirements and recommendations in the text be numbered or identified by their URI. ex: Requirement 1 vs. Requirement /req/core/http

ghobona commented 2 years ago

Requirements and other specification elements should be identified by URI (e.g. /req/core/http).

However, to make it easier to read the document, we let metanorma automatically number the Requirements.

References from other specification elements to Requirements should use the URIs of the referenced Requirements.

cmheazel commented 2 years ago

Part numbers (A, B, etc.) in requirements, recommendations and permissions lack sufficient spacing in the Word rendering. There are no clear delimiters between requirements, recommendations, or permissions in the Word rendering. If there is no text between two instances, they run together visually. Also, the format used in this pull request does not match the template. Shouldn't we agree on a template that works for all renderings before updating approved standards?

ghobona commented 2 years ago

@cmheazel Please only review the HTML and PDF documents. OGC only publishes HTML and PDF documents.