Consider switching from Madoko to AsciiDoc for P4Runtime specification

[jafingerhut]

Why? Because Madoko is no longer maintained as of 2019, and at least the P4 Language Design work group is considering switching from Madoko to AsciiDoc because of this. While the current Madoko sources can be used to generate PDF and HTML on Ubuntu 20.04, using the same steps fails on Ubuntu 22.04 and Ubuntu 24.04. See here for more details: p4lang/p4-spec#1115

I have created a draft of a conversion from Madoko to AsciiDoc for the P4 language specification, and while it was a bit tedious and fiddly, most of the text doesn't change. The generated PDF and HTML output have a bit different look-and-feel, which you can see linked from here: p4lang/p4-spec#1115 (comment)

I have kept some notes during my process of creating the AsciiDoc version of the P4 language specification, here: https://github.com/jafingerhut/learn-asciidoc/blob/main/p4-spec-next/README-madoko-to-asciidoc-notes.md

I suspect very similar steps would apply for the P4 Runtime specification. If there is interest in moving to AsciiDoc, let me know, and I can probably find some time to create a similar proposed AsciiDoc source version of the P4Runtime spec for your consideration.

[smolkaj]

Thanks for taking the initiative on this!

+1, I'm strongly in favor for following suite with the P4 LDWG and adopting the same solution they do here.

[chrispsommers]

Agreed, +1

[Dscano]

I have started the migration, so it is currently a work in progress. The source files and instructions for generating the HTML and PDF can be found here: jafingerhut/learn-asciidoc#6.