Align and standardise metadata in final CF documentation artifacts (PDF and HTML)

[cofinoa]

Moderator

@cofinoa

Requirement Summary

The final CF documentation artifacts (PDF and HTML) should expose clear, consistent, and standards-friendly metadata suitable for indexing, citation, and long-term archival (e.g. Zenodo, libraries, search engines). At present, metadata is incomplete, partially inconsistent, and not fully aligned with current standards or best practices.

This does not affect the normative content of the CF conventions or the conformance documents.

Technical Proposal Summary

Introduce a minimal and consistent metadata model for the final CF artifacts (PDF and HTML), aligned with widely recognised standards (e.g. Dublin Core, modern HTML metadata, PDF 2.0 / ISO 32000), without changing any normative content of the CF specification.

Benefits

• Better discoverability and indexing of CF documentation.
• Cleaner and more accurate metadata for Zenodo and other archives.
• Clear separation between publication metadata and build/tooling metadata.
• Improved consistency between PDF and HTML artifacts.

Status Quo

Currently:

• PDF Producer contains incorrect information. According to the PDF standard, Producer and Creator are intended to describe the software used to create and produce the PDF, not the document authors. At present, authors are incorrectly listed in Producer.
• Creator reflects tooling, which is appropriate, but is not clearly distinguished from content authorship.
• PDF metadata does not include Description, Keywords, or explicit CF version information.
• HTML metadata is minimal, tool-generated, and not aligned with standard vocabularies.
• Metadata is not consistently aligned between PDF, HTML, and conformance documents.
• There is no explicit alignment with newer PDF metadata practices (PDF 2.0 / ISO 32000).

Associated pull request

None at present.

Detailed Proposal

This issue proposes to:

1. Define a small, explicit set of metadata fields for CF artifacts:

   • Title
   • CF version
   • Publication date
   • Authors and affiliations
   • Description
   • Keywords
   • Persistent identifier (DOI)
   • Build timestamp (clearly distinct from publication date)

2. For PDF artifacts:

   • Correct the semantics of Producer and Creator, ensuring they identify the software toolchain used to generate the PDF, as intended by the PDF standard.
   • Add missing descriptive metadata (e.g. Description, Keywords).
   • Move towards metadata structures compatible with PDF 2.0 / ISO 32000 where feasible.

3. For HTML artifacts:

   • Improve and standardise <meta> entries.
   • Align HTML metadata with PDF metadata.
   • Use widely recognised, community-standard metadata conventions.

4. Apply the same principles consistently to both the CF specification and the conformance document.

5. Evaluate and implement these improvements using the existing Asciidoctor-based toolchain where possible. The tools already in use appear to support most of the required metadata without major plumbing changes, but this should be confirmed carefully to avoid unnecessary complexity or over-engineering.

All changes should be incremental, tooling-compatible, and non-normative.

[JonathanGregory]

Dear Antonio

Thanks for this proposal. In case others are as unaware as me, may I clarify that you're referring to metadata which is stored in the PDF and HTML files but not generally displayed by PDF readers or web browsers. Actually I didn't know it was there! It's easy to see the HTML <meta> tags by viewing the page source in the web brower, but I hadn't. I see it says

<meta name="generator" content="Asciidoctor 2.0.20">
<meta name="author" content="Brian&#160;Eaton, Jonathan&#160;Gregory, Bob&#160;Drach, Karl&#160;Taylor, Steve&#160;Hankin, ...">

and I can read the PDF metadata with pdftk PDFfilename dump_data

InfoKey: Creator
InfoValue: Asciidoctor PDF 2.3.4, based on Prawn 2.4.0
InfoBegin
InfoKey: ModDate
InfoValue: D:20251217143903+00'00'
InfoBegin
InfoKey: CreationDate
InfoValue: D:20260127235816+00'00'
InfoBegin
InfoKey: Producer
InfoValue: Brian Eaton, Jonathan Gregory, Bob Drach, Karl Taylor, Steve Hankin, ...
InfoBegin
InfoKey: Author
InfoValue: Brian Eaton, Jonathan Gregory, Bob Drach, Karl Taylor, Steve Hankin, ...
InfoBegin
InfoKey: Title
InfoValue: NetCDF Climate and Forecast (CF) Metadata Conventions

I see what you mean! Yes, it would clearly be a good idea to make this metadata consistent and conformant to appropriate standards. I support the proposal.

Jonathan

[cofinoa]

Thanks Jonathan, that’s exactly the point.

I jumped too quickly into the technical details without first showing a concrete example of the metadata that is already present in the PDF and HTML artefacts. Your walkthrough (HTML <meta> tags and PDF info fields) makes the problem much clearer. Thanks for spelling it out.

As you say, this is all about embedded publication metadata that is not normally visible to readers, but is important for indexing, citation, and archiving.

Glad that the proposal makes sense. The challenge now is to articulate what the appropriate standards should be. I think we need a clear reference to good practices, without going into too much technical detail.

I'll try to make a proposal and see how it fits into the tooling for building the artifacts.

[DocOtak]

I fully support this proposal and effort as well.

[larsbarring]

Same here -- full support from me.