Include a link to the CF website within the conventions document

[JonathanGregory]

Title

Include a link to the CF website within the conventions document

Moderator

None yet

Moderator Status Review

None yet

Benefits

An obvious link will inform anyone about the CF website who doesn't know of it. This may particularly help someone who has only the PDF. It will also provide a convenient way to navigate from the document (back) to the website. This proposal arises from a comment on the discuss issue #152 by @jypeter.

Brief proposal overview

Include a new paragraph just below the list of authors and version number, on the first page of the PDF, and above the horizontal rule and table of contents in the HTML, as follows:

The latest release, current draft and all previous versions of this document can be found on the CF website at cfconventions.org. Please visit the website for the standard name table and other controlled vocabularies, forums for questions and proposals about the conventions, a list of software for working with CF, and other resources.

Associated pull request

#464

[JonathanGregory]

I wonder whether any of those at the hackathon have an opinion on this proposal, which would be very easy to implement: to include a link to the CF website within the conventions document. The suggested text is

The latest release, current draft and all previous versions of this document can be found on the CF website at cfconventions.org. Please visit the website for the standard name table and other controlled vocabularies, forums for questions and proposals about the conventions, a list of software for working with CF, and other resources.

[taylor13]

Where they are mentioned in Jonathan's proposed text, I would include specific links to "controlled vocabularies" (https://cfconventions.org/Data/cf-standard-names/current/build/cf-standard-name-table.html), forums for questions and proposals ( https://cfconventions.org/discussion.html), and software (???).

A couple of related tweaks to consider, which I think would make it easier to navigate:

• in the readme file on https://github.com/cf-convention/discuss provide links to the CF website, akin to those on the https://github.com/cf-convention/cf-conventions readme.
• on the discussion overview page I would remove the text "using GitHub issues." There is little of relevance there and I accidentally clicked on it assuming it would lead to the conventions discussion pages.

[JonathanGregory]

Dear Karl @taylor13

Of course you're right that we could include links directly to controlled vocabularies etc. within the CF document. However, my proposal is only to link cfconventions.org, because this means no maintenance will be required. Any links to other items on the website might change; for instance, we are elsewhere discussing renaming the "standard name" page as "vocabularies". We see from the experience of our links to resources external to CF within the document that they tend to get broken in this way. Updates to the CF website can occur at any time, unrelated to the CF standard, so the same is just as likely to happen to them.
Instead of providing more links within the CF document, I would prefer that we make sure that the CF home page clearly signposts where you should look for the various resources within the website.

Best wishes

Jonathan

[jypeter]

We need at least one link from the convention document to the convention website (hopefully a URL that will not change in the near future, and has been paid in advance). And then make sure all the supporting information/documents can be easily found from the website homepage

If possible, we could also have the same paragraph (with the link) at the very end of the document (maybe a footer of the last page), because the obvious place to look for a link is at the top and/or the end of a document

[taylor13]

@JonathanGregory, I accept your justification for omitting links in the obvious places. And I agree with you and @jypeter, we should make every effort to improve the links from the main page to supporting information/documents.

[larsbarring]

Am I correct in interpreting the views expressed in the comments that there is acceptance for including a (one) link to the main web page http://cfconventions.org/ in the Conventions document? If so, I suggest that this link is placed at the very beginning, after authors and version / release date. I.e. something like

NetCDF Climate and Forecast (CF) Metadata Conventions

Brian Eaton Jonathan Gregory Bob Drach Karl Taylor Steve Hankin Jon Blower John Caron Rich Signell Phil ....
... ...
-version 1.11 draft, 31 August, 2022
-The Climate and Forecasting Conventions website http://cfconventions.org/ contains additional resources and provides further information.

Table of Contents

....
....

The text surrounding the web page link is of course only tentative, please feel free improve.

[larsbarring]

Hm, by pure chance I came across the Preface, which already has a link to the home page and some surrounding text. If this is considered sufficient then this issue can be closed (as is evident, personally I do not think that it is the most obvious place to look for a home page link, but I will bow to other views).

[JonathanGregory]

Well spotted, @larsbarring. As you say, it's not prominent enough. I wonder if we should put the contents of the "preface" before the table of contents instead of where it is now, so it appears just after the version number and list of authors. What do you think? That is essentially what you suggested before.

[jypeter]

I had never noticed this Preface section and I find it a bit confusing, both in the HTML and pdf part of the documentation

It is not really a preface (the abstract is the preface!), is it? It actually describes the content of the CF web site, for somebody who would have access only to the pdf version of the documentation, or somebody browsing the HTML version of the documentation who would not be able to navigate back to the home page

I think it would make more sense, if we keep this section, to rename Preface to CF convention web site and possibly change its content to something like

Home page: http://cfconventions.org/

The CF Convention web site contains links to this document and the working draft of the next version,
as well as CF-related links such as applications for processing CF conforming files, email list for discussion
about interpretation, clarification, and proposals for changes or extensions to the current conventions. 

And I would put Revision history

• either at the end of the Abstract section,
• or in its own (even if it is small) section, between "CF convention web site" and "1. Introduction"

And I would anyway keep the link to the website below the version number, on the first page, as suggested by Lars

[larsbarring]

I think that we are discussing two rather separate things here, just because they happen to coexist in the Preface:

1. A good place to put the link to the home page
2. Where to put the Revision history

Regarding (1), I think that moving all of the Preface text up before the Table of Content is not so attractive. First of all, the part on revisions does not belong there (at all), and secondly (less strong argument) is that I think the explanation of the Home page is a bit too long. I was thinking more of a one-liner.

Regarding (2), I think that the revision history itself is located all right now, at the end of the document. Ideally I think that it should be located in Appendix G, where it should be according to the TOC. But this might not be possible, or difficult using the automatic document build process.

Based on this I suggest that we delete the Preface section, and move the text related to the home page up after some editing to shorten it.

EDIT: Added boldface "not"

[jypeter]

Sounds good, thanks! Especially with the Revision history already being in the document (whether it is in Appendix G or at the end of the document)

[JonathanGregory]

Dear Lars

I agree the revision history is in the right place, at the end of the document. That is where we decided to put it when we changed to asciidoc. It used to be an appendix. We should change the title and doc entry of Appendix G to "(empty)" or something like that. We kept it, even though it has no content except for the notice that you should look at the end, so that subsequent appendices did not have to change their letter.

I agree that it would be fine to delete the Preface and put a one-line statement about the home page to precede the table of contents.

Best wishes

Jonathan

[larsbarring]

Thanks @jypeter and @JonathanGregory, I will prepare a PR.

[larsbarring]

After closer inspection I will not create a PR myself because the Preface is located in file "pr01.adoc". And removing this file would likely upset the build process. Hence someone knowledgeable about this needs to do it or at least help out.

[DocOtak]

@jypeter @larsbarring For the URL itself, it is very much best practice these days to prefer the https version i.e.

• use https://cfconventions.org/
• not http://cfconventions.org/

[larsbarring]

I have just created a (draft) PR. The formatting/layout is not ideal but this is as far as I manage without any detailed knowledge of AsciiDoc. I would have preferred to have no section heading and a smaller font size. Moreover, in the pdf version this small section ends up on a separate page instead of at the bottom of the front page.

[JonathanGregory]

Dear @larsbarring

Thanks for working on this. After some investigation of the asciidoc documentation, I wonder whether this would match your intentions a bit better:

include::version.adoc[]
:revremark: See https://cfconventions.org/ for further information
= NetCDF Climate and Forecast (CF) Metadata Conventions
Brian{nbsp}Eaton; Jonathan{nbsp}Gregory; Bob{nbsp}Drach; Karl{nbsp}Taylor; ...; Lars{nbsp}Bärring
{current-version}, 31 August, 2022

This puts "See https://cfconventions.org/ for further information" on the same line as the version. I've shortened this so that it fits into the line in both HTML and PDF.

Ideally, we would like to make it longer and on its own line. I was hoping there might be a way to embed a newline at the start of the revremark, but I can't work out the syntax (if there is one) for enabling character replacements in the revremark, and I don't know if there is a character which would produce a newline anyway---perhaps
 i.e. ASCII linefeed character.

Jonathan

[larsbarring]

Thanks @JonathanGregory
Yes, I agree that this is a reasonable solution. Based on your suggestion I found this slightly simpler alternative:

...
Anders{nbsp}Meier{nbsp}Soerensen; Lucile{nbsp}Gaultier; Sylvain{nbsp}Herlédan; Fernando{nbsp}Manzano; Lars{nbsp}Bärring
Version {current-version}, 31 August, 2022: See https://cfconventions.org for further information
:doctype: book

Irrespective of which alternative, one drawback is that the link is not "live". For the web version it is not much of a problem as it is not difficult to find the right link in the browser address line. For the pdf version it is however more of an issue. The solution I found was to modify the default running footer line in the pdf. I tried to hack into the theme file in the repo, but it turned out that it is not in use. And when I tried using it there were warnings about references to old/deprecated styles and what not. Thus I removed it and instead I copied the default theme file and changed the footer to include the same text. And now the links become "live" in the footer.

NOTE to the Information Management and Support Team:
To make use of the new theme file a small change has to be made to the github workflow file adoc_build.yml:

...
shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -d book --theme default-theme-with-footer.yml \
cf-conventions.adoc -D conventions_build'
...

(the [relative] path the the theme file might have to be changed)

[JonathanGregory]

Dear @larsbarring

This means the CF website URL will appear at the bottom of every page in the PDF - is that right? That's clever. Does the HTML version have the footer too? Would it be possible and useful to include the version number in the footer as well using {current_version}?

Best wishes

Jonathan

[larsbarring]

Regarding pdf here is a screenshot

The html version do not have the "bottom-of-page" concept, so I think that it is not possible/relevant.

In principle we could include the version in the footer. Or, possibly we could create a running header including the title and version.

But a key thing here is that this is implemented in the github workflow for creating/publishing the documents.

[JonathanGregory]

Dear @larsbarring

In view of this comment in the Asciidoctor GitHub, I wonder whether the link on the title page would be rendered as "live" in the PDF if it was prefixed with link: in the adoc file.

Best wishes

Jonathan

[larsbarring]

And here is a version with running hreader and running footer:

I could not get link: to work, it just showed up as regular text. Maybe someone in the IMST could figure out whether the html line

<br><span id="revremark">See https://cfconventions.org for further information</span>

could be automagically changed (monkey-patched) in the github workflow after creation to read

<br><span id="revremark">See <a href="https://cfconventions.org" target="_blank">https://cfconventions.org</a> for further information</a></span>

[JonathanGregory]

I like the header and footer! Thanks.

[jypeter]

So do I. We can now find the requested information everywhere!

[larsbarring]

Thanks @JonathanGregory and @jypeter.

Now it is up to the Information Management and Support Team:
To make use of the new theme file a small change has to be made to the github workflow file adoc_build.yml:

...
shellcommand: 'asciidoctor-pdf --verbose ${FINAL_TAG} -d book --theme default-theme-CF-version.yml \
cf-conventions.adoc -D conventions_build'
...

(the [relative] path the the theme file might have to be changed)

Finally, when I ran the asciidoc-pdf a couple of warnings/errors showed up:

$ asciidoctor-pdf --verbose ${FINAL_TAG} -d book --theme ./default-theme-with-footer.yml --trace cf-conventions.adoc 
asciidoctor: INFO: possible invalid reference: example_interpolation_of_cell_boundaries
asciidoctor: ERROR: the table cell on page 198 has been truncated; Asciidoctor PDF does not support table cell content that exceeds the height of a single page
asciidoctor: INFO: possible invalid reference: dimensionless-v-coord
asciidoctor: INFO: possible invalid reference: preface

I did not look into these, but it might be worthwhile for someone more involved with those parts of the conventions text.

[larsbarring]

PS. I think that someone from the Information Management and Support Team should merge the associated PR #464 to make sure that the required changes are made in the github workflow.

Thanks,
Lars

[larsbarring]

Many thanks @davidhassell for taking care of the github workflow and other details in the PR #464! I think that the it is ready to be merged, but perhaps someone else shoul have a look and approve (or comment) before.

[davidhassell]

Hi Lars, I just need to to submit my change - I'll let you know when it's ready to merge

[davidhassell]

Oh - I see that my change already is in (not had coffee yet, this morning :)). I agree that this is ready to merge!

[davidhassell]

Hello,

I was wondering why the new default-theme-CF-version.yml file doesn't include these lines from the original no-lead-theme.yml in the "font: catalog:" section:

    # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols
    # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font
    M+ 1p Fallback:
      normal: mplus1p-regular-fallback.ttf
      bold: mplus1p-regular-fallback.ttf
      italic: mplus1p-regular-fallback.ttf
      bold_italic: mplus1p-regular-fallback.ttf
  fallbacks:
    - M+ 1p Fallback

Was that deliberate?

[larsbarring]

I was trying to modify the old theme file, but eventually when I "got it working" the result was an error message that some of the ttf files were missing. So I went to the asciidoctor repo and found a new default theme file default-theme.yml that I modified.

[davidhassell]

Hi Lars, that makes sense, thanks. Were those warning coming from the GitHub actions, or your local install? I don't get such warnings with my local setup. I guess that GitHub action are OK with it, because it's been there for ages (but perhaps we've been ignoring the warnings?).

The reason I spotted this is because the presence of that block affects how the bare <= are rendered (#472).

[larsbarring]

The warnings/errors came from my local install, and I know from a totally different context that it can be very easy to miss at least warnings generated in the workflow. The comment was more a heads up than a claim that something really is wrong.

I have very little experience or insight in asciidoc[tor], but given that, was the old theme file actually used at all? When I tested adding the footer nothing happened at all until I added the -theme ... command line parameter and then I got the error.

But that was my local install, perhaps the theme file is activated through some other mechanism in the github workflow? In that case we should keep the old one and just add the parts specifically dealing with the header and footer.

[larsbarring]

The last few comments, which were positive, regarding layout and content of this change were on October 17. Subsequent comments relates to the technical implementation. Counting three weeks from 17 October, I suggest that the associated PR #464 could be merged on November 7 (which happens to be today ... :-)