Open jafingerhut opened 1 month ago
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.
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.
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
I submitted a PR to Andy's repository that solved the PDF page layout issues.
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?
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
@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.
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.
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, :)
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:
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: