Experiments for OGC standard template

javagl commented 2 years ago

For now, this inserts only the header from the community standard template.

Assuming that you already can run "Metanorma", the command line

metanorma compile --agree-to-terms -t ogc -x html,pdf Specification.adoc

should generate a PDF file (the HTML output is still broken...)

Build instructions will be added here or in the BUILDING.md soon. Fow now, I can only give the recommendation to NOT install Metanorma, but instead, use the Docker container. (Details of how to use the Docker container to build the specs will also be added, as soon as I have figured that one out...)

A preliminary list of TODOs, derived from warnings or issues during the build process:

Warnings that are caused by a wrong structure:

(): Keywords are missing!
(): Submitting Organizations is missing!
(): Submitters is missing!
(): Prefatory material must be followed by (clause) Scope
(): Scope must be followed by Conformance
(): Normative References must be followed by Terms and Definitions
(): Normative References are mandatory
(): Abstract is missing!

Most of them should be easy to fix, by adding the sections as described in https://www.metanorma.org/author/ogc/authoring-guide/sections-ogc/ , or adding things like :submitting-organizations: ... to the current header in Specification.adoc

Each code snippet is considered to be a 'Figure', and is listed in the 'List of Figures' ... with an empty title. There may be an option to tell Metanorma that [source] is not a 'Figure'...
Each table will need a title, to be properly listed in the 'List of Tables'
For the HTML output, there is an error message that is probably caused by the fact that images are inlined as data URIs. Actually, this should not be the default. There is an AsciiDoc :data-uri: option to enable this, and a Metanorma --no-datauriimage CLI Option to disable it, but this does not seem to have any effect

javagl commented 2 years ago

The recent commits address some of the issues above:

The issue about the large image in the HTML has been resolved by replacing a large PNG with a smaller JPG
The code snippets are no longer counted as figures, by marking them as [%unnumbered]
Titles for all tables have been inserted

Some further fixes are PRELIMINARY and have to be reviewed:

Abstract is missing! Treat the single introductory sentence "This document describes the specification for 3D Tiles, an open standard for streaming massive heterogeneous 3D geospatial datasets." as the 'abstract' - TO BE REVIEWED / EXTENDED
Keywords are missing!
- Added the "tags" from the GitHub 3d-tiles repo as keywords terrain, geospatial, gis, point-cloud, spatial-data, vector-data, photogrammetry, gltf, 3d-models, 3d-tiles - TO BE REVIEWED
Submitting Organizations is missing!
- Added CesiumGS Inc. - TO BE REVIEWED
Submitters is missing!
- There is a section Submitters, but the table is still empty - TO BE FILLED
Normative References are mandatory
- Added BIBLIPGRAPHY.adoc and TERMS_AND_DEFINITIONS.adoc, but these are still empty - TO BE FILLED
Preface is missing! Prefatory material must be followed by (clause) Scope Scope must be followed by Conformance Normative References must be followed by Terms and Definitions
- Still trying to figure out what they want there...

lilleyse commented 2 years ago

@javagl the guidance document linked in https://docs.ogc.org/pol/05-020r27/05-020r27.html#main-steps-in-the-standard-process goes into more detail about the preface/scope:

Documents being submitted as Full standards shall use the document formatting and content, in common use by the OGC at the time of submission, of standards submitted under the OGC Consensus Standards process. There is a detailed guidance document for using the template.

Documents being submitted as Community standards do not need to follow the OGC document template for an OGC standard. However, the submission team for a Community standard is strongly encouraged to provide the candidate standard to the OGC using the document template.

You might be able to reference the 3D Tiles 1.0 submission too: https://github.com/CesiumGS/3d-tiles/blob/main/specification/specification.pdf

javagl commented 2 years ago

There have been some updates

Added "Terms And Definitions"
Added "References"
Extended "Revision History"

This is largely based on the 3D Tiles 1.0 spec from https://github.com/metanorma/mn-samples-ogc/blob/main/sources/18-053r2/ , so they may be incomplete (i.e. we should check which additional entries 1. and 2. need , and keep an eye on https://www.metanorma.org/author/ogc/authoring-guide/terms-definitions/#entering-terminology-entries ).

The Revision History is taken from 1.0 - I assume that this should be done, because we are in fact only updating the 1.0 specification.

There have been some tweaks in the section structure, trying to minimize the number of warnings (and make sections appear properly in the TOC), but ... a "warning-free" state might be an unachievable ideal. (I'm not even talking about the ~100 "Matenorma XML syntax" warnings, but the "coarse-grained" ones that indicate wrong section orders, regardless of the order of the sections...)

A spec-lawyer detail: https://www.metanorma.org/author/ogc/topics/markup/ says

Where section obligations are named (i.e. in annex names), they are only given as “normative” or “informative”; the alternate text of “non-normative” is disallowed.

While this only seems to refer the whole sections, we are declaring inlined sections (implementation examples) as 'non-normative' (and use the term "Implementation Note" occasionally to declare non-normativeness). Should that be changed/reviewed?

javagl commented 2 years ago

I'll mark this as 'Ready for review' for now.

EDIT: One possibly important thing is the information in the document header, like the 'Submission date' or 'document identifiers'. We don't know them for now, I guess.

The mandatory sections for Metanorma/OGC have been inserted and filled, even though they may require polishing. For example, the 'Normative References' and 'Terms And Definitions' are largely taken from 3D Tiles 1.0. I have added some terms (from Metadata and Implicit Tiling), but they still may have to be extended or reviewed in terms of their actual 'normative-ness' and details of the wording.

Currently, the "Property Reference" is marked as the only 'normative' appendix, because it is the only sensible summary of all structures and their properties. (Most of them are described in the actual spec text, but not as formally/technically as in the properties reference). The 'Conformance' section explicitly links to the 'Properties Reference' as part of the definition of 'conformance'.

The changes that have been done in this branch are made under the assumption that the final document will be created with Metanorma. It is still possible to run the plain, 'old' asciidoctor on the current state, and the output looks somewhat OK, but if the intention was (medium-term) to create a "nice" document with plain asciidoctor, then some of the OCG sections (submitters, conformance...) might be omitted. This would be possible with some asciidoctor --attribute create-ocg-version.... command line flag, but that's probably not pressing right now.

lilleyse commented 2 years ago

I'm seeing a bunch of warnings from metanorma. Which of these need to be addressed and which are just noise?

(base) slilley@Hydrogen:~/Code/3d-tiles/specification$ docker run -v "$(pwd)":/metanorma -v ${HOME}/.fontist/fonts/:/config/fonts metanorma/metanorma metanorma compile --agree-to-terms -t ogc -x html,pdf Specification.adoc
Calling `DidYouMean::SPELL_CHECKERS.merge!(error_name => spell_checker)' has been deprecated. Please call `DidYouMean.correct_error(error_name, spell_checker)' instead.
Top level ::CompositeIO is deprecated, require 'multipart/post' and use `Multipart::Post::CompositeReadIO` instead!
Top level ::Parts is deprecated, require 'multipart/post' and use `Multipart::Post::Parts` instead!
[relaton] EPSG WGS-84-3 does not have a recognised prefix
[relaton] Khronos Group glTF 2.0 does not have a recognised prefix
[relaton-w3c] ("W3C css-color-3") fetching...
[relaton-ietf] ("IETF RFC 2397") fetching...
[relaton-ogc] ("OGC 12-063r5") fetching...
[relaton-ietf] ("IETF RFC 2397") found RFC 2397
[relaton-ogc] ("OGC 12-063r5") found 12-063r5
[relaton-ietf] ("IETF RFC 3629") fetching...
[relaton-w3c] ("W3C css-color-3") found css-color-3
[relaton-ietf] ("IETF RFC 3629") found RFC 3629
[relaton-ietf] ("IETF RFC 3986") fetching...
[relaton-ietf] ("IETF RFC 3986") found RFC 3986
[relaton] EPSG WGS-84-3 does not have a recognised prefix
[relaton] Khronos Group glTF 2.0 does not have a recognised prefix
Style: Preface is missing!
Metanorma XML Style Warning: (XML Line 000428): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 000454): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 000493): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 000679): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 000908): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001008): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001129): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001361): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001500): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001612): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001643): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001662): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001849): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001862): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001931): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001944): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 001997): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002045): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002132): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002151): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002209): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002314): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002346): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002383): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002459): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002503): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002516): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002567): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002671): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002716): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002742): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002936): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 002951): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003122): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003261): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003277): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003365): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003414): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003808): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003831): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003874): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 003927): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 004728): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 004769): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 004839): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 005201): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 005371): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006013): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006097): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006207): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006291): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006494): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006593): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006698): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006820): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 006929): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 007277): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 007395): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 007494): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 007631): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 007758): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 008063): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 008153): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 008417): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 008507): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 008771): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 008855): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 008979): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009196): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009250): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009414): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009489): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009581): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009761): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009905): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 009996): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 010052): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 010246): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 010326): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 010546): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 010671): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 012907): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 013125): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 013145): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 013254): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 013266): Hanging paragraph in clause
Metanorma XML Style Warning: (XML Line 000018): Figure should have title
Metanorma XML Style Warning: (XML Line 000018): Figure should have title
Metanorma XML Style Warning: (XML Line 000024): Table should have title
Metanorma XML Style Warning: (XML Line 003890): Table should have title
Metanorma XML Style Warning: (XML Line 003963): Table should have title
Metanorma XML Style Warning: (XML Line 003975): Table should have title
Metanorma XML Style Warning: (XML Line 004195): Table should have title
Metanorma XML Style Warning: (XML Line 004414): Table should have title
Metanorma XML Style Warning: (XML Line 004428): Table should have title
Metanorma XML Style Warning: (XML Line 013874): Table should have title
Metanorma XML Syntax: (XML Line 000140:104): element "clause" not allowed here; expected element "foreword"
Metanorma XML Syntax: (XML Line 000140:290): element "submitters" not allowed yet; missing required element "foreword"
Metanorma XML Syntax: (XML Line 000193:174): element "fn" not allowed here; expected the element end-tag, text or element "add", "bookmark", "br", "concept", "del", "em", "eref", "hi", "hr", "image", "index", "index-xref", "keyword", "link", "note", "pagebreak", "ruby", "smallcap", "span", "stem", "strike", "strong", "sub", "sup", "svg", "tt", "underline" or "xref"
Metanorma XML Syntax: (XML Line 000236:330): element "fn" not allowed here; expected the element end-tag, text or element "add", "bookmark", "br", "concept", "del", "em", "eref", "hi", "hr", "image", "index", "index-xref", "keyword", "link", "note", "pagebreak", "ruby", "smallcap", "span", "stem", "strike", "strong", "sub", "sup", "svg", "tt", "underline" or "xref"
Metanorma XML Syntax: (XML Line 003258:47): element "p" not allowed here; expected the element end-tag
Metanorma XML Syntax: (XML Line 003456:52): element "figure" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 003956:51): element "table" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004031:51): element "table" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004043:51): element "table" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004263:51): element "table" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004411:52): element "figure" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004456:52): element "figure" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004463:52): element "figure" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004482:51): element "table" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 004496:51): element "table" not allowed here; expected the element end-tag or element "dl", "formula", "ol", "p", "quote", "sourcecode" or "ul"
Metanorma XML Syntax: (XML Line 014042:123): element "docidentifier" not allowed yet; missing required element "title"
Metanorma XML Syntax: (XML Line 014076:145): element "docidentifier" not allowed yet; missing required element "title"
java -Xss5m -Xmx2048m -jar /usr/local/bundle/gems/mn2pdf-1.47/lib/../bin/mn2pdf.jar --xml-file "/metanorma/Specification.presentation.xml" --xsl-file "/usr/local/bundle/gems/metanorma-ogc-2.1.3/lib/isodoc/ogc/ogc.community-standard.xsl" --pdf-file "/metanorma/Specification.pdf" --syntax-highlight  --font-manifest "/tmp/fontist_locations20220627-1-sarrz9.yml"

javagl commented 2 years ago

As mentioned above: A "warning-free" state might be an unachievable ideal.

But to roughly categorize the messages

[relaton] EPSG WGS-84-3 does not have a recognised prefix [relaton] Khronos Group glTF 2.0 does not have a recognised prefix

This refers to the functionality of auto-fetching reference information for certain types of references (e.g. for ISO standard references or so). We might change the reference to use one of the "known reference repository identifiers", but I think this is mainly a convenience, compared to manually defining it.

Style: Preface is missing! ... required element "foreword"

We can add a section called Preface and 'Foreword'. I don't know what it should contain, though. The "Abstract", "Scope" and "Conformance" already felt a bit handwaving...

... element "table" not allowed here; expected ... ... element "figure" not allowed here; expected ...

These seem to be mostly caused by the cases where we have tables and images in admonitions (i.e. in the 'Note'-blocks). Why it prints a warning for that? I don't know...

Hanging paragraph in clause ... element ... not allowed here; ...

🤷‍♂️

I can look at the code/rule that generated this message, and I can look at the XML to see the offending elements, but I don't know why they are not allowed there, or where these elements come from in the first place.

From my understanding, the approach of Metanorma, on the oversimplified level, is

Take any input (HTML, ADOC, MD, DOC, ...)
Convert it into an 'XML to rule them all'
Perform some sanity checks on the XML
Use the XML to generate any output (HTML, PDF, DOC, ...)

Now, many things can go wrong there. I did not yet go down to the level where I'd try to debug the Ruby code that is running inside the Docker container or so. But I can investigate these warnings, on demand...

javagl commented 2 years ago

An aside: In the command line that is used for creating the specs, one can add

... -x html,pdf,xml
                ^ this

in order to retain this XML file that the warnings refer to.

lilleyse commented 2 years ago

The Revision History is taken from 1.0 - I assume that this should be done, because we are in fact only updating the 1.0 specification.

I think revision history is specific to the document based on what I've seen in other OGC specs. So the table should have a single row with a description like "This is the first normative version of this document."

While this only seems to refer the whole sections, we are declaring inlined sections (implementation examples) as 'non-normative' (and use the term "Implementation Note" occasionally to declare non-normativeness). Should that be changed/reviewed?

Yeah, let's change the wording to "informative" everywhere.

Other comments:

Should Gabby still be included as an editor in this revision? I don't know what standard practice is...
Submission date: we'll need to update this right before submitting
Approval date: leave blank
Publication date: leave blank
External identifier of this OGC® document: leave blank
Internal identifier: use 22-025. I just reserved this identifier in the OGC portal.
Keywords
- remove hyphens
- remove vector data
- add: "metadata" "implicit tiling"
Preface: let's include this section since I see it in most other OGC specs. This would be section V. I don't see Foreword as often, so we can omit that. Maybe just copy the first paragraph of the preface in https://github.com/CesiumGS/3d-tiles/blob/main/specification/specification.pdf
Add "Future Work" section. This would be section VI. Copy the first paragraph from https://github.com/CesiumGS/3d-tiles/blob/main/specification/specification.pdf
Add "Conventions" section. This would be section 5 - I see it in other OGC specs even if it is left blank. Copy the section in https://github.com/CesiumGS/3d-tiles/blob/main/specification/specification.pdf
Update WKT normative reference to be the latest WKT spec https://docs.opengeospatial.org/is/18-010r7/18-010r7.html. This seems to be related to the note in the 3D Tiles 1.0 preface.
Conformance - I find the conformance section in https://github.com/CesiumGS/3d-tiles/blob/main/specification/specification.pdf to be a little clearer. Maybe copy it, update the sections numbers, and link to Appendix B (JSON schema reference). As a side note, one OGC spec I looked at simply says "Not required in an OGC Community Standard." :shrug:
Add EPSG:4978 to normative references (in addition to EPSG:4979). Link to the official site (e.g. https://epsg.org/crs_4978/WGS-84.html) instead of https://spatialreference.org/. There might be a few links in the spec body that need to be updated as well.
"A binary blob containing information necessary to render a tile which is an instance of a specific tile format (Batched 3D Model, Instanced 3D Model, Point Clouds, or Composite)." -- include glTF in this definition
"The structure or layout of tile content data, (Batched 3D Model, Instanced 3D Model, Point Clouds, or Composite)." - include glTF in this definition
JSON encoding and URIs sections - are all the documents here included in the Normative References section?
I took a look at OGC Policy Directive 49 - we should try to use the same language wherever possible. The biggest thing is changing "must" to "shall" everywhere.

lilleyse commented 2 years ago

The HTML output seems to be missing "List of Tables" and "List of Figures" (possibly a bug in the HTML generator since there's no table of contents in the HTML output?). Most likely out of our control.

javagl commented 2 years ago

Condensed revision history
Changed "Implementation Note" and "...non-normative" to "informative"
Changed all dates and identifiers to TBD. (This causes warnings - they want a date there)
Updated keywords as requested
Added 'Preface', 'Future Work', 'Conventions' - note that the section numbering (roman vs. arabic numbers) uses some internal magic - I think it just starts with the arabic 1. at 'Scope' - and the order of the sections does not match the order in the input file...
Wording updates for 'Conformance' section Note:

Maybe copy it, update the sections numbers, and link to Appendix B (JSON schema reference).

I assume that this should link to the 'Properties Reference' (or do we want to make the schema reference normative?)
Added glTF in list of tile formats in 'Terms and Definitions'
Updated/extended the 'References' (WKT, EPSG, JSON encoding)

I took a look at OGC Policy Directive 49 - we should try to use the same language wherever possible. The biggest thing is changing "must" to "shall" everywhere.

The word 'must' appears 209 times in the specification. I can go through these and see which of them ~~must~~ shall be changed. But many of them appear in the properties reference, so this may rather be an issue of https://github.com/CesiumGS/wetzel/blob/82890df68ae4c24c5679196c06e3afccd6673a30/lib/style.js#L132 ...

An aside: Among the XML warnings is one

element "fn" not allowed

This is caused by footnotes. In the PDF, footnotes appear at the bottom of the page. In the HTML, they appear ... at the bottom ... of ... everything. I think we should avoid footnotes, and just use a plain link instead (there are only 2 of them).

javagl commented 2 years ago

I'm still wondering about all the "Hanging paragraph in clause" messages. If someone who knows Ruby can decipher what it is actually checking here https://www.rubydoc.info/gems/metanorma-standoc/1.9.3/Asciidoctor/Standoc/Validate#hanging_para_style-instance_method that could help.

For a moment, I thought that it might actually complain about "empty" clauses: From other standardization efforts, I know that it is sometimes considered to be problematic to have sections like

1. Section

1.1. First Subsection

Some text here

1.2. Second Subsection

More text here

because there is no text in 'Section 1' (but only in the Subsections), and there should always be some text, like

1. Section

Now here is some text that sets the stage for the following subsections

1.1. First Subsection

Some text here

1.2. Second Subsection

More text here

(We could do this anyhow, but from a first quick test, that's not what Metanorma complains about ...)

lilleyse commented 2 years ago

@javagl I pushed some commits:

Updated the editors
Added the 22-025 doc number
Updated the conformance section. My read of it is that it's the properties reference section that's referring to the JSON schema section. I updated accordingly.
Somehow the changes in https://github.com/CesiumGS/3d-tiles/pull/690 got lost in the draft-1.1 branch. I made those changes here.

javagl commented 2 years ago

💡 this "MIME type" vs. "madia type" change was only applied to the .MD files. Sorry about that.

lilleyse commented 2 years ago

Hmm... so we can't control where the Future Work section goes? It doesn't feel right to include it in the main spec body when it really belongs in the preliminary sections. That seems to be the convention for other specs too.

lilleyse commented 2 years ago

The word 'must' appears 209 times in the specification. I can go through these and see which of them ~~must~~ shall be changed. But many of them appear in the properties reference, so this may rather be an issue of https://github.com/CesiumGS/wetzel/blob/82890df68ae4c24c5679196c06e3afccd6673a30/lib/style.js#L132 ...

Yeah let's update all those, including the wetzel branch (and regenerate the property reference)

javagl commented 2 years ago

Apparently, it can be tagged as [.preface] - from https://www.metanorma.org/author/ogc/authoring-guide/sections-ogc/#ogc-additional-prelim - which is "allowed but not encouraged"...

Metanorma Future Work

So it could be done, if desired...

javagl commented 2 years ago

The point about wetzel: Sorry, I said something that was ... essentially wrong there. Wetzel does insert the "must-keyword" at some places, but there is nothing to fix in wetzel itself - just to add -k "shall" to the command line.

Beyond that, most appearances of 'must' are from the description in the schema, so this will indeed be a rather manual process.

(I can tackle that a bit later today)

lilleyse commented 2 years ago

Apparently, it can be tagged as [.preface] - from https://www.metanorma.org/author/ogc/authoring-guide/sections-ogc/#ogc-additional-prelim - which is "allowed but not encouraged"...

Let's do it. Even the OGC Standard for Modular specifications includes it in the preliminary sections.

javagl commented 2 years ago

The change from 'must' to 'shall' was done in the last commits. (It could largely have been done with a "Replace all", but I did it manually. I also changed it in 'Informative' sections, even though it should not matter there...)

Being aware of similar requirements ( https://datatracker.ietf.org/doc/html/rfc2119 ), the wording in most parts of the specification text SHOULD already be reasonably precise in terms of the exact meaning of these keywords, but I think that it has not been reviewed explicitly in this regard.

lilleyse commented 2 years ago

I did a quick final pass over the HTML and PDF. I don't think there's anything left to add here. Thanks @javagl!

javagl commented 2 years ago

For a moment, I thought that it might actually complain about "empty" clauses: From other standardization efforts, I know that it is sometimes considered to be problematic to have sections like ...

Another thing that might come up in terms of ~"broad, editorial/typesetting practices" is that we often do not refer to images and tables in the text. As far as I know, patterns like

Some data can be stored in some way.

Some Table A B

X Y

Some Table	A	B
X	Y

should rather be linked, as in

Some data can be stored as shown in Some Table ...

But we'll fix that if it actually comes up.

lilleyse commented 1 year ago

The code snippets are no longer counted as figures, by marking them as [%unnumbered]

@javagl did this change go back into the wetzel branch? I regenerated the property reference just now and the lines were removed.

javagl commented 1 year ago

@lilleyse It might well be that I did this manually in the rush back then, but ... doing the fix wouldn't have taken much longer, so I just opened https://github.com/CesiumGS/wetzel/pull/84 ...

(EDIT: Of course, one could argue about whether this should be configurable via the wetzel CLI, but ... I think having them unnumbered is a sensible default...)

lilleyse commented 1 year ago

Thanks @javagl

CesiumGS / 3d-tiles

Experiments for OGC standard template #700

1. Section

1.1. First Subsection

1.2. Second Subsection

1. Section

1.1. First Subsection

1.2. Second Subsection