Switching from Madoko to AsciiDoc for P4Runtime specification

[Dscano]

I am currently in the process of transitioning the P4Runtime specification from Madoko to AsciiDoc. Below is an overview of the remaining tasks:

• I need to fix the layout of two tables in the P4Runtime-spec.adoc file.
• Finalize the reorganization and changes necessary for folder structure to support the switch from Madoko to AsciiDoc.

[jafingerhut]

I tried make in the docs/v1 directory on a Linux system, and got this error:

$ make
make: *** No rule to make target 'P4Runtime-Spec.adoc', needed by 'P4Runtime-Spec.pdf'.  Stop.

Note the capitalization of the S in Spec. The file name in your PR is P4Runtime-spec.adoc with a lower-case s in spec.

I would recommend leaving the Makefile as it is now, and renaming the .adoc file to match the current capitalization of the Madoko source file.

[jafingerhut]

The file logo.png is missing.

[jafingerhut]

Need to update the markup for the URL at the end of Section 1 -- in the PDF output it shows up as https://...

[jafingerhut]

At least some cross-references to figures are rendered in PDF as "Figure Figure 1". In Madoko it was necessary to say "Figure [#crossref-tag]" in the source, but the "Figure" is redundant in AsciiDoc. Similarly for section and table references.

[jafingerhut]

In the first paragraph of Section 4, a sentence in the PDF ends with "are described in a laterChapter 5." It would be better if it were "are described in Chapter 5". Either that or if "later chapter" were a link to Chapter 5, like I see for some other cross-references.

[jafingerhut]

Most or all of the figures could use some tweaking on the percent of the column width they occupy, to make them smaller. See the P4 language spec AsciiDoc source for examples.

[jafingerhut]

You use [source,p4] at the beginning of snippet of Protobuf definitions. Does Rouge support [source,protobuf]? I am guessing from the existence of a lexer for Protobuf here that it should: https://github.com/rouge-ruby/rouge/blob/master/lib/rouge/lexers/protobuf.rb

[jafingerhut]

The paragraph at the end of Section 6.4.3 ActionProfile looks blank in the PDF, probably because in the source it has spaces at the beginning of each line. Something should be done to improve that, probably deleting those leading spaces so the text comes out as a normal paragraph after the bullet list.

It is not clear to me, but perhaps those spaces were there intending for that text to be part of the last bullet, or something like that? If so, there are probably different markups in AsciiDoc that can achieve that, but given that it looks like a separate paragraph in the current Madoko PDF output, making it look like a separate paragraph in the AsciiDoc PDF output is a good start.

Similarly for some text inside a bullet list in the section with title "Meter & DirectMeter".

Also for a bullet list in the section with title "Batch Atomicity".

I experimented in a few places with ways to achieve this in the P4 language spec AsciiDoc source. I don't recall exactly which parts right now, but if you have trouble finding examples of it, let me know and I can try to find them. In the P4-16-spec.adoc file, search for the string "interface of a Match-Action" for an example of using a line containing only + to continue a bullet item in the next paragraph (if I recall correctly), or surrounding a paragraph with -- lines before and after.

Here is some AsciiDoctor documentation on this topic: https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/

[jafingerhut]

Compare the section heading "depths" of all section headings in the current Madoko PDF output, and the AsciiDoc PDF output. At least "Counter & DirectCounter" is Section 6.4.4 in Madoko PDF output, but Section 6.5 in AsciiDoc PDF output.

[jafingerhut]

In the section titled "Extern", need whitespace after "reserved range" and before the range.

[jafingerhut]

In one of the markups that should be "cite:", it is misspelled "cte:"

[jafingerhut]

In the section titled "Bytestrings" there are some LaTeX math formulas. There are a few such formulas in the P4 language spec, too, that I was able to get to render properly using AsciiDoc. Search for occurrences of "latexmath" in the P4 language spec AsciiDoc source for examples.

[jafingerhut]

There is at least one remaining occurrence of [@PSATranslation] that should be updated to cite:[PSATranslation]. Also one occurrence of [@PSAActionSelector].

[jafingerhut]

One cross-reference with text [P4 Entity Messages](#sec-p4-entity-msgs) section needs to be updated to AsciiDoc.

[jafingerhut]

There is an occurrence of "WriteRequests" that should be replaced with "WriteRequests" for AsciiDoc. See here for some examples of differences I found when translating the P4 language spec: https://github.com/jafingerhut/learn-asciidoc/blob/main/p4-spec-next/README-madoko-to-asciidoc-notes.md#monospace

[jafingerhut]

Probably most occurrences of using $ to mark up algebra or math should be replaced with a backtick, unless they need fancier symbols, then latexmath is probably needed. There are many occurrences of $ remaining in the P4Runtime AsciiDoc.

[jafingerhut]

The section heading for the section named "Examples of StreamError Messages" needs at least one blank line before it, or else AsciiDoc does not interpret it as a section header.

There is also an old Madoko-style cross-reference markup on the line before that.

Similarly for section heading "Changes in v1.3.0"

[jafingerhut]

In the section "Changes in v1.4.0", the first sub-bullet item under "Actions" needs to be nested one level deeper.

[jafingerhut]

In section "P4Runtime Entries files" the sequence of bash commands needs different markup. Not sure, but maybe [source,bash] will work?

[Dscano]

FYI, the comments were I "react" with a thumbs-up have been addressed in c43d938

[jafingerhut]

FYI, the comments were I "react" with a thumbs-up have been addressed in c43d938

Great! Please let me know when you are ready for another round of review, i.e. when for each review comment you have either made changes, or replied in some way that you believe no changes are needed.

[Dscano]

You use [source,p4] at the beginning of snippet of Protobuf definitions. Does Rouge support [source,protobuf]? I am guessing from the existence of a lexer for Protobuf here that it should: https://github.com/rouge-ruby/rouge/blob/master/lib/rouge/lexers/protobuf.rb

I applied it to a few proto code blocks (such as 6.1.2) so we can compare and see how it looks.

[chrispsommers]

@chrispsommers @smolkaj @jafingerhut Thank you for the comments. I will address them as soon as possible.

And if you are willing to merge this in before the list of things you have pointed out have been changed, Davide and I can use the comments on this PR (even after it is closed, linked from a new open issue), to track the comments you have made on this PR.

@smolkaj I'm OK with merging now and following up with the minor issues as time allows; wdyt?

[jafingerhut]

I believe I have captured all of the net-yet-resolved comments on this PR in their own separate issues on this repo. All of them have had the new label "asciidoc-issue" added to them.

[chrispsommers]

I believe I have captured all of the net-yet-resolved comments on this PR in their own separate issues on this repo. All of them have had the new label "asciidoc-issue" added to them.

Thanks, I saw that. Waiting for @smolkaj 's opinion, I'm ready to merge if he is.

[chrispsommers]

I believe the space between asciidoc and -lint is causing this failure: https://github.com/p4lang/p4runtime/actions/runs/12320523043

[chrispsommers]

Check failures need to be addressed

[Dscano]

I had to update the Dockerfile.asciidoc because the previous version was not working correctly.

[Dscano]

I have resolved the issues:

• Use correct Asciidoc markup for em-dashes #528
• Fix incorrect markup for creating links in Asciidoc output #529

I have proposed a solution for issue #525

[jafingerhut]

I think we need to restore lines like these in the Makefile, otherwise running make in the docs/v1 directory fails to find the .svg and .png image files.

[Dscano]

Indeed, we have 2 use cases:

• If the Docker runs on a host machine, the user needs to generate the PNG images and then compile.
• If the Docker has to run on a CI server, the images must be generated within the make process or checked in beforehand.

[jafingerhut]

But we can reduce all cases to behave in a way where whether it is a bare metal system, a VM, or a container, the Makefile has the commands that generate the .svg/.png files from the OpenOffice source files, by installing LibreOffice on the system, yes? I thought that was the preference that Chris expressed earlier, and that is why we only have the OpenOffice files checked in, not the .svg/.png files.

Even if there are cases where the .svg/.png files are sitting there, running make with a Makefile that contains rules for generating those files will only generate them if they are needed, so I don't see only advantages to having these rules in the Makefile that can generate them.

[jafingerhut]

Sorry, one more quick comment, in case this is something I am confused about.

If there are any containers anywhere that anyone wants to use to generate the PDF & HTML for the P4Runtime spec, I think we should tell them: "Install LibreOffice in that container, or it won't work."

And if there is some container published by someone in the P4 community that you want to use, that installs asciidoctor, but not LibreOffice, I think we should ask them to update that container so that it does contain LibreOffice, even if LibreOffice is only needed for generating the P4Runtime spec.

[Dscano]

Totally agree with you. Does this mean we need to implement it for the container running in the CI environment?

[jafingerhut]

I have resolved the issues:

• Use correct Asciidoc markup for em-dashes #528
• Fix incorrect markup for creating links in Asciidoc output #529

I have proposed a solution for issue #525

I have regenerated the PDF and HTML files for the latest version of AsciiDoc input files on this PR as of 2024-Dec-24, with the commits Davide mentions above, and put them in the same place I put earlier versions, here: https://github.com/jafingerhut/learn-asciidoc/tree/main/p4runtime-spec-next/sample-generates-files

I spot-checked the fixes for the em-dashes and the correct link, and they both look good to me. Thanks.