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: https://github.com/p4lang/p4-spec/issues/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: https://github.com/p4lang/p4-spec/issues/1115#issuecomment-2115323019

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: https://github.com/jafingerhut/learn-asciidoc/pull/6.

[jafingerhut]

FYI, the P4 language and Portable Switch Architectures are now officially AsciiDoc source. The "working draft" links for those two on this page now point at the generated PDF and HTML, generated from AsciiDoc: https://p4.org/specs/

Yes, the look & feel is definitely not the same as the Madoko generated PDF and HTML -- hopefully we can either find it good-enough, or find ways to tweak the style options in the future to improve it, but mostly it seems pretty good.

@chrispsommers @smolkaj If you would like to do the same for the P4Runtime spec, realize that any open PRs will likely need to be updated, and/or recreated from scratch, when you make this switchover. There are only 2 open PRs for the P4Runtime spec right now, so it seems perhaps like a good time to make the switch soon, if you want to. If you do, I would guess @Dscano might be convinced to update his work to correspond to the latest version of the P4Runtime Madoko spec, and create a PR for this repo.

@Dscano if you do, I would recommend the following when creating such a PR:

• first do git mv P4Runtime-Spec.mdk P4Runtime-spec.adoc to rename the file
• then copy the AsciiDoc version over the renamed file P4Runtime-Spec.adoc

Why? Because even though many lines of the file will be changing, there will also be many lines that remain the same, and it would be nice of git log and git blame commands on that file continued to show as much of the history as we can.

[Dscano]

@jafingerhut perfect, @smolkaj @chrispsommers let me know if I can proceed.

[chrispsommers]

@Dscano I didn't realize you were offering to do the conversion yourself. But if I read this correctly, you're offering to perform the migration for this repo? If so, thanks so much, please do proceed. If I misread it, we'll still welcome your advice.

[Dscano]

@Dscano I didn't realize you were offering to do the conversion yourself. But if I read this correctly, you're offering to perform the migration for this repo? If so, thanks so much, please do proceed. If I misread it, we'll still welcome your advice.

Perfect, I'll take care of it.

[Dscano]

You can find the first draft here https://github.com/p4lang/p4runtime/pull/510