Consider AsciiDoc for future format of source for P4 language specification

[jafingerhut]

For background, see https://github.com/p4lang/p4-spec/issues/1115

As detailed at the issue linked above, while Ubuntu 20.04 can install Madoko tools to build the specification PDF and HTML files, this no longer works on later versions of Ubuntu Linux. Madoko, which has been used since the P4_16 language specification began, is no longer maintained as of 2019.

One possible replacement is AsciiDoc.

Several people have created an example of what AsciiDoc source for the P4 language specification can look like, and what the HTML and PDF generated from it looks like. There are many configuration options that can change the look and feel of the generated HTML and PDF, so the links below should not be considered the only way that it can be made to look, but it does require some time and effort to learn how to modify the AsciiDoc, and/or the tools used to generate HTML and PDF, to change the visual style.

Latest status as of 2024-Aug-04: Updated PDF and HTML below slightly on 2024-Aug-08 to modify font size in code snippets:

Davide Scano has spent several weeks modifying the configuration and style sheets to produce the latest version of the generated HTML and PDF, which can be seen at these links:

• HTML - https://jafingerhut.github.io/p4-spec-next/P4-16-spec.html
• PDF - https://jafingerhut.github.io/p4-spec-next/P4-16-spec.pdf

The source files, and instructions for generating the HTML and PDF, can be found here: https://github.com/jafingerhut/learn-asciidoc

Other things of potential interest:

• Notes I made while converting the Madoko source file into the AsciiDoc source file, with differences on the two flavors of markup: https://github.com/jafingerhut/learn-asciidoc/blob/main/p4-spec-next/README-madoko-to-asciidoc-notes.md
  • In particular, note the lack of widow/orphan control in the current AsciiDoc->PDF generation: https://github.com/jafingerhut/learn-asciidoc/blob/main/p4-spec-next/README-madoko-to-asciidoc-notes.md#widoworphan-line-control
• Notes on my manual comparison of the PDF output from Madoko, vs. the PDF output from AsciiDoc: https://github.com/jafingerhut/learn-asciidoc/blob/main/p4-spec-next/README-differences-between-madoko-and-asciidoc-pdf.md

[rcgoodfellow]

Thanks! This looks great and closely resembles what the spec looks like today. I know asciidoctor has the ability to render the TOC as a sidebar. Wondering if there is interest in that. However, that should not block things moving forward. Having an asciidoc render of the spec that is really close to what we have today is a great starting point and solves the issues with using Madoko on modern systems.

[Dscano]

Thanks! This looks great and closely resembles what the spec looks like today. I know asciidoctor has the ability to render the TOC as a sidebar. Wondering if there is interest in that. However, that should not block things moving forward. Having an asciidoc render of the spec that is really close to what we have today is a great starting point and solves the issues with using Madoko on modern systems.

I'll be more than happy to adjust the style or add additional elements. Imho, what I'm proposing now in the PR is a starting point for a collective discussion.

[ChrisDodd]

One issue I noticed with the PDF version (also present in the html but less noticeable) is that it appears to be using a larger font for the code example blocks. This results in some of them with longer lines wrapping and being less legible as a result. Worst case seems to be the example block at the end of 6.8.2

[Dscano]

I submitted a PR to Andy's repository that solved the PDF page layout issues.

[Dscano]

Thanks! This looks great and closely resembles what the spec looks like today. I know asciidoctor has the ability to render the TOC as a sidebar. Wondering if there is interest in that. However, that should not block things moving forward. Having an asciidoc render of the spec that is really close to what we have today is a great starting point and solves the issues with using Madoko on modern systems.

It's already in the PDF; are you referring to the HTML version?

[jafingerhut]

One issue I noticed with the PDF version (also present in the html but less noticeable) is that it appears to be using a larger font for the code example blocks. This results in some of them with longer lines wrapping and being less legible as a result. Worst case seems to be the example block at the end of 6.8.2

Davide made some changes to the style sheets that should have improved this.

For the particular example of the code block at the end of 6.8.2, note that one goes outside of the 'bounding box' even in the Madoko version. I would argue the code text should be changed from the current text:

package pack<HP, MP, HC, MC>(@optional parserProto<HP, MP> _parser,  // optional parameter
                             controlProto<HC, MC> _control = nothing()); // default parameter value

to something with shorter lines, like this:

package pack<HP, MP, HC, MC>(
    @optional parserProto<HP, MP> _parser,  // optional parameter
    controlProto<HC, MC> _control = nothing()); // default parameter value

[jafingerhut]

@ChrisDodd https://github.com/p4lang/p4-spec/pull/1300 to shorten a few lines that are already too long for Madoko to avoid wrapping or escaping their shaded box.

[rcgoodfellow]

Thanks! This looks great and closely resembles what the spec looks like today. I know asciidoctor has the ability to render the TOC as a sidebar. Wondering if there is interest in that. However, that should not block things moving forward. Having an asciidoc render of the spec that is really close to what we have today is a great starting point and solves the issues with using Madoko on modern systems.

It's already in the PDF; are you referring to the HTML version?

Yeah, I was referring to the HTML version. Again, this is not something that should block this initial effort, but it is something to think about moving forward.

[Dscano]

Thanks! This looks great and closely resembles what the spec looks like today. I know asciidoctor has the ability to render the TOC as a sidebar. Wondering if there is interest in that. However, that should not block things moving forward. Having an asciidoc render of the spec that is really close to what we have today is a great starting point and solves the issues with using Madoko on modern systems.

It's already in the PDF; are you referring to the HTML version?

Yeah, I was referring to the HTML version. Again, this is not something that should block this initial effort, but it is something to think about moving forward.

Done, :)