Add documentation on published specifications and how P4.org finds them

[jafingerhut]

No description provided.

[jafingerhut]

@rcgoodfellow Some proposed docs on how the "Working draft" links on the P4.org specification pages work today.

[jafingerhut]

@rcgoodfellow Do your Github actions for building the HTML and PDF from the AsciiDoc source, put the resulting HTML and PDF files in a place with a known URL that does not change from one run of the Github actions to the next?

If so, we can update the little HTML files on the P4.org server mentioned in this PR, to load those new URLs, instead of the URLs that they load now.

[rcgoodfellow]

Do your Github actions for building the HTML and PDF from the AsciiDoc source, put the resulting HTML and PDF files in a place with a known URL that does not change from one run of the Github actions to the next?

The artifact URLs change from run to run. They are of the form:

https://github.com/p4lang/p4-spec/actions/runs/$run_id/artifacts/$artifact_id

The deploy job is pushing artifacts to the gh-pages branch in an attempt to match the madoku behavior.

I've noticed that images are not rendering from the page

• https://p4.org/p4-spec/docs/p4-16-working-draft.html

I'll look into that as soon as I can.

[rcgoodfellow]

The links are still relevant today, as the Asciidoc CI mechanisms are still publishing files to these URLs.

[jafingerhut]

It is a space optimization, not a must-have, but at least the older way of generating Madoko PDF and HTML grew the Git history of the p4-spec repo on every commit, because I believe it was keeping the full commit history of all PDF and HTML generated versions.

The P4Runtime spec does not do that -- it uses a different way of publishing the generated PDF and HTML that always overwrites the previous PDF and HTML versions with the latest one, not keeping around the history. See #1287 for a few more details if you are curious. It might be as small of a difference as a single command line option to one git command somewhere.

While you are investigating this, it would be nice if we could curb the future growth of the p4-spec repo in this same way.