Problems in the github document build process

[larsbarring]

Problems in the github document build process

Moderator

not yet

Requirement Summary

The published conventions documents (html and pdf) have to reflect the content of the source files. This should be fixed before release of version 1.11.

Benefits

All users (and producers) of the CF conventions documents.

Status Quo

The documents do not fully represent the original source (adoc) text.

Associated pull request

non yet

Detailed Proposal

I have observed some errors and warnings issued by asciidoctor and asciidoctor-pdf when building the conventions documents. These should be dealt with so that the documents are as expected from the source *.adoc files.

Technical Proposal Summary

This is just a heads up for a couple of issues that I saw when checking the github CI checks of #475 (see here)

Here is a screenshot of result of the html build

The first two warnings relates to internal references (links) are dead and should be fixed.
The third one is because the Preface section is now deleted, while the link is still there in the history as it was in a previous version. This link could be deleted, or, if we really want to fully honour the historical development, the link could perhaps be kept despite it is dead.

And here is the corresponding one for the pdf build

Note that when the pdf is built a table cell cannot not overflow to the next page, meaning that the text is truncated. This is a known limitation of asciidoctor-pdf, see https://docs.asciidoctor.org/pdf-converter/latest/features/#limitations.. If I quickly (not really knowing what the text is about) scan the build it seems that the text on pdf page 204 is truncated. It ends with:

...spanned by va and vb, the vector representations of the two tie points,
and expressed as a fraction of the length of A x B.

But in the html version the text continues (no line breaks as it is html):

...spanned by va and vb, the vector representations of the two tie points, and expressed as a fraction of the length of A x B.

For interpolation in three-dimensional cartesian coordinates as the coefficients cv = (cv.x, cv.y, cv.z), expressing the offset components along the three-dimensional cartesian axes X, Y and Z respectively.

For interpolation in geographic coordinates latitude and longitude as the coefficients cll = (cll.lat, cll.lon), expressing the offset components along the longitude and latitude directions respectively.

The functions fq() and fw() referenced in the following are defined in Quadratic Interpolation. "

@davidhassell I tentatively assign this to you because I think that you have detailed knowledge of Appendix J. Of course, feel free change this.

[larsbarring]

Note that these problems were present before the recent changes to the build process, see e.g. this action: https://github.com/cf-convention/cf-conventions/actions/runs/6319747690

[davidhassell]

Hi @larsbarring - glad to be assigned! I shall have a look.

My first thought on the PDF truncation is to refactor that table (and the four similar others) to not be tables. I think (and recall) that there was nothing functional about the tabular format, it was just a convenient formatting device.

[larsbarring]

I think that whatever solution you think is useful, is a good one.

[davidhassell]

Hi Lars, PR #488 should address all of these problems.

It involves reformatting the tabular structure of part of Appendix J, and simply correcting the invalid internal references.

The new Appendix J can be compared with the old one, and the resulting GitHub action is at https://github.com/cf-convention/cf-conventions/actions/runs/6980590776/job/18996136129.

[larsbarring]

Yes, I had a quick look at the changes in the PR --- not anything like checking for typos and the like --- and it looks good. I like the formatting of formula boxes, they are easier to read. And the asciidoctor errors/warnings are gone. So, I would say that this PR is good to go. Thanks David!

[davidhassell]

Thanks, Lars. I guess we can give it a few days gestation, and then merge it just before the release during the week after next. I'll put the 1.11 milestone on the PR so we don't forget.

[larsbarring]

Closed as completed via #488