Embed images into HTML document

[cofinoa]

Associated pull request

PR #522

The proposed PR #522 modifies the Github action which renders the HTML document of the convention, to embed images into the HTML document, instead of refer images as external file.

This has the advantage of having just one file, for the whole HTML convention document, like the PDF rendered version.

[cofinoa]

The PR #522 also includes a version update for the GH actions

[JonathanGregory]

Thank you, Antonio @cofinoa. Do you have an example of what the HTML looks like?

[cofinoa]

@JonathanGregory in PR #522 run checks summary and artifacts has been uploaded to:
https://github.com/cf-convention/cf-conventions/actions/runs/9383208743?pr=522

where you can find an artifact for the conformance document, and the artifact for the PDF and HTML documents.

[JonathanGregory]

Ah, I see. Each image is included as a string representation of its image data in the src of the img tags. That makes the html file bigger, I suppose, but it is still only half the size of the pdf. Thanks.

[cofinoa]

Yes!, it makes the HTML file itself bigger.

Also, the image content is BASE64 encoded, adding and overhead between 33%-37% with respect to the original binary data.

But, the good side it's that only on file it's needed for the HTML document. Therefore, it's trade-off

[larsbarring]

The advantage is when one wants to download the html for offline access it is one file (~3.2 Mb), instead of either getting the html file without images (~840 kb), or the html file and an image directory (~840kb + ~1.9 Mb) depending on how the download is done. As it now is, If I uses Firefox to download the HTML link on the webpage I get the former, but if I open the html document in Firefox and then save the the document I get the latter. But I imagine this may differ between web browsers.

Anyway, the size difference is about 1 Mb, which is not excessive, and I think there is merit to always get the full document without having to think of a separate image subdirectory. Thanks Antonio. I will have a look at the PR, but I am far from an expert on gh workflows.

[JonathanGregory]

Thanks for implementing this in #522, Antonio @cofinoa. I agree with you that it'll be a good improvement, and I don't know a reason why it shouldn't be included in 1.12. Jonathan

[JonathanGregory]

Is it ready to be merged, Antonio @cofinoa? @larsbarring and I expressed for support for it more than three months ago, so it qualifies to be accepted, I think. I'd like to have @davidhassell's opinion, as the person in charge of the conventions document.

[cofinoa]

I'm updating the build process taking into account some comments from @davidhassell

After that, @davidhassell will review the PR and check that it's OK

[davidhassell]

Hi Antonio,

I have just fetched a copy of your PR [*], typed make in the my local cf-conventions directory ... and it work perfectly! I.e. it created the following files, all of which had the correct images embedded in them:

conformance_build/conformance.html
conformance_build/conformance.pdf
conventions_build/cf-conventions.html
conventions_build/cf-conventions.pdf

I also tried

$ make clean; make
$ make clean; make html
$ make clean; make pdf
$ make clean; make html pdf
$ make clean; make all
$ make clean; make conformance
$ make clean; make conventions

which also worked as expected.

This is marvellous - thank you! I'm happy for this to be merged.

We should make it known that this capability exists, as as it will be useful to anyone writing PRs.

Cheers,
David

[*]

$ git fetch upstream pull/522/head:cofinoa-embed-html-img
$ git checkout cofinoa-embed-html-img

[JonathanGregory]

Thanks again for this, Antonio @cofinoa. @davidhassell is quite right to describe it as "marvellous" - maybe even magical! Now that he's checked it too, and since it's received more than enough support to be accepted, I will merge it.