Experiments for OGC standard template #700
Conversation
javagl
changed the title
Metanorma HTML output limits the image file size, and 11MB was just too large.
|
The recent commits address some of the issues above:
Some further fixes are PRELIMINARY and have to be reviewed:
|
|
@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:
You might be able to reference the 3D Tiles 1.0 submission too: https://github.com/CesiumGS/3d-tiles/blob/main/specification/specification.pdf |
|
There have been some updates
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
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? |
This is based on the "Glossary" that was formerly part of the Implicit Tiling extension specification.
Based on the terms in the Metadata introduction. Certainly not perfect...
|
I'll mark this as 'Ready for review' for now.
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 |
|
I'm seeing a bunch of warnings from metanorma. Which of these need to be addressed and which are just noise? |
|
As mentioned above: A "warning-free" state might be an unachievable ideal. But to roughly categorize the messages
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.
We can add a section called
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...
🤷♂️ 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
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... |
|
An aside: In the command line that is used for creating the specs, one can add in order to retain this XML file that the warnings refer to. |
…/3d-tiles into draft-1.1-ogc-experiments
The word 'must' appears 209 times in the specification. I can go through these and see which of them An aside: Among the XML warnings is one
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). |
|
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
because there is no text in 'Section 1' (but only in the Subsections), and there should always be some text, like
(We could do this anyhow, but from a first quick test, that's not what Metanorma complains about ...) |
There was a problem hiding this comment.
EDITED: This is obsolete as of the comment below
I'm suprised - did the 'MIME' slip back in at some point after b46c42d#diff-8034c95ee174226b9529fb7896346c6b53f7d421e34c78607ab0e2055f1913ce ? (I think I did a full text search for 'MIME' back then, and can hardly imagine having overlooked this...)
|
@javagl I pushed some commits:
|
|
💡 this "MIME type" vs. "madia type" change was only applied to the |
|
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. |
Yeah let's update all those, including the wetzel branch (and regenerate the property reference) |
|
Apparently, it can be tagged as
So it could be done, if desired... |
|
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 Beyond that, most appearances of 'must' are from the (I can tackle that a bit later today) |
Let's do it. Even the OGC Standard for Modular specifications includes it in the preliminary sections. |
Partially addressing OGC Policy Directive 49
Partially addressing OGC Policy Directive 49
Partially addressing OGC Policy Directive 49
Consistency for the changes done to the core 1.1. schema files
|
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. |
|
I did a quick final pass over the HTML and PDF. I don't think there's anything left to add here. Thanks @javagl! |
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
should rather be linked, as in
But we'll fix that if it actually comes up. |
@javagl did this change go back into the wetzel branch? I regenerated the property reference just now and the lines were removed.
|
|
@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 CesiumGS/wetzel#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...) |
|
Thanks @javagl |
For now, this inserts only the header from the community standard template.
Assuming that you already can run "Metanorma", the command line
should generate a PDF file (the HTML output is still broken...)
Build instructions will be added here or in the
BUILDING.mdsoon. 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:
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.adocEach 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-datauriimageCLI Option to disable it, but this does not seem to have any effect