search

metanorma / mn-samples-ogc

Metanorma for OGC sample documents
1 stars 2 forks source link

Converted 17-069r3 OGC document #36

Closed anermina closed 4 years ago

anermina commented 4 years ago

Notes:

  1. Front page differs.
  2. List of tables is included in the generated document, unlike in the original document.
  3. Generated document cross-references "Clauses", while the original document uses "Sections".
  4. References in the generated document include less detail.
  5. Order of the first two paragraphs in Terms and definitions section is different (first paragraph is added automatically, and in this case it should be added below the intro of this section, i.e. as the second paragraph).
  6. Terms are written below subsection numbers in the generated document, while they are written next to the number in the original document.
  7. Links are missing for some of the cross-references in the original document, and are therefore missing in the generated document as well. E.g: "Validate that all response documents comply with /ats/core/fc-md-links" "Validate that all response documents comply with /ats/core/fc-md-items" In this specific case, maybe "/req/core/fc-md-items-links" should have been cross-referenced? However, there is a few more cross-references which don't lead to any section/link in the original document.
  8. Sections before the Scope are not included in ToC of the original document, but they appear in the ToC of the generated document.
  9. Examples have double titles and they are not numbered properly.
  10. Two tables are numbered with 1 - the one in the preface and the first one in the main text.
  11. Preface isn't numbered.
  12. Source codes with captions are shown as figures (similar to the first caption in the examples).
ronaldtse commented 4 years ago

Resolution to notes:

Front page differs.

Accepted since it is the new layout.

List of tables is included in the generated document, unlike in the original document.

Accepted since it is the new layout.

Generated document cross-references "Clauses", while the original document uses "Sections".

Accepted since it is the new layout.

References in the generated document include less detail.

What kind of details should we have? Can you provide some examples? Are the bibliogrpahic items encoded properly?

Order of the first two paragraphs in Terms and definitions section is different (first paragraph is added automatically, and in this case it should be added below the intro of this section, i.e. as the second paragraph).

Accepted since it is the new layout.

Terms are written below subsection numbers in the generated document, while they are written next to the number in the original document.

Accepted since it is the new layout.

Links are missing for some of the cross-references in the original document, and are therefore missing in the generated document as well. E.g: "Validate that all response documents comply with /ats/core/fc-md-links"

These are errors inherited from the source document so it's fine.

"Validate that all response documents comply with /ats/core/fc-md-items" In this specific case, maybe "/req/core/fc-md-items-links" should have been cross-referenced? However, there is a few more cross-references which don't lead to any section/link in the original document.

Errors inherited from the source document are fine.

Sections before the Scope are not included in ToC of the original document, but they appear in the ToC of the generated document.

Accepted since it is the new layout.

Examples have double titles and they are not numbered properly.

Will file new issue.

Two tables are numbered with 1 - the one in the preface and the first one in the main text.

This is an issue.

Preface isn't numbered.

I think this is fixed?

Source codes with captions are shown as figures (similar to the first caption in the examples).

These blocks need to be marked [%unumbered] to not be numbered.

@anermina could you please help do two things in subsequent document migrations?

  1. All cross-references must be resolved. These errors should not show when compiling.
IDREF "query_param_invalid" without matching ID @ 1835:124
IDREF "ats_core_fc_md_links" without matching ID @ 3368:132
IDREF "ats_core_fc_md_items" without matching ID @ 3371:132
IDREF "rec_geojson" without matching ID @ 508:216
IDREF "rec_geojson" without matching ID @ 670:296
IDREF "data_wbp" without matching ID @ 339:240
IDREF "rec_html" without matching ID @ 508:173
IDREF "rec_html" without matching ID @ 669:71
No label has been processed for ID data_wbp
No label has been processed for ID rec_html
No label has been processed for ID rec_geojson
No label has been processed for ID two_approaches_oas
No label has been processed for ID query_param_invalid
No label has been processed for ID ats_core_fc_md_links
No label has been processed for ID ats_core_fc_md_items

When there are links that are missing or cannot be encoded, add a comment inside the text.

  1. Please use the current convention for document structure, where there is a sections folder and the entry point document is named document.adoc.

Thanks!

ronaldtse commented 4 years ago

Two tables are numbered with 1 - the one in the preface and the first one in the main text.

This is verified fixed. The prefix table isn't numbered now.

anermina commented 4 years ago

References

What kind of details should we have? Can you provide some examples? Are the bibliogrpahic items encoded properly?

It seems to me that RFC descriptions are taken from some other source. They are encoded the same way as the other bibliographic items, but while the others render properly, RFC items have some descriptions different from the encoded ones.

Original: image

Generated: image

Example of encodings:

Preface

I think this is fixed?

Yes, it's fixed.

Source code

These blocks need to be marked [%unumbered] to not be numbered.

[%unnumbered] is added in #60 .

General

@anermina could you please help do two things in subsequent document migrations?

I will keep this in mind. Thank you!

ronaldtse commented 4 years ago

@anermina re: bibliographic items:

You might realize that the IETF references are "auto-fetched" (https://www.metanorma.com/author/topics/building/reference-lookup/)

(and ISO, IEC, ITU, OGC, NIST ...)

This is a manual rendering of a bibliographic item:

* [[[openapi,Open API Initiative]]], Open API Initiative: OpenAPI Specification 3.0.2, 2018 https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md

This is an auto-fetched document, and is identical in effect to:

* [[[rfc2616,RFC 2616]]], Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T.: IETF RFC 2616, HTTP/1.1, 1999 http://tools.ietf.org/rfc/rfc2616.txt

SAME AS:

* [[[rfc2616,RFC 2616]]]

Is this the difference you see?

ronaldtse commented 4 years ago

Remaining question from @anermina moved to #61 .