search

p4lang / p4-spec

Apache License 2.0
178 stars 80 forks source link

Replace Madoko version of P4_16 language spec with AsciiDoc #1317

Closed jafingerhut closed 2 weeks ago

jafingerhut commented 1 month ago

Also update install script, Makefile, grammar, remove files that are no longer used because they were only used in generating PDF and HTML from the old Madoko source, and add font and theme files used in generating PDF and HTML from the AsciiDoc source.

You can find HTML and PDF files generated from this AsciiDoc and other files in this PR, here: https://github.com/jafingerhut/learn-asciidoc/tree/main/p4-spec-next/sample-generated-files

A summary of some differences I have noticed between the PDF generated from Madoko, vs. the PDF generated from AsciiDoc, can be found at the link below. Feel free to let me know any others you find, especially if you wish it were changed in the AsciiDoc version:

The bash install script setup-for-ubuntu-linux.sh modified in this PR should be able to successfully install AsciiDoctor and other required programs to generate HTML and PDF from AsciiDoc source on any of Ubuntu 20.04, 22.04, or 24.04 systems. I have personally tested it (as of commit 3 of this PR) on all of those, on both x86_64 and aarch64 (aka arm64) processor architecture systems, with the exception of (aarch64 + Ubuntu 22.04) where I was not able to successfully install that version on that system.

jafingerhut commented 1 month ago

Thanks to Davide Scano for doing all the work on the resources/theme/* files and their interaction with the AsciiDoc generation process, and for lots of other improvements leading to better generated PDF and HTML files.

Minor note: I first modified the P4-16-spec.mdk file by copying the AsciiDoc source over that file, then I renamed it. My hope is that for the majority of the lines of the spec that are not changing, their revision history, e.g. output from git blame, will remain the same as before.

jafingerhut commented 2 weeks ago

Hmm, we are not complying with DCO on all of these commits. Github gives instructions for fixing that with a few commands, but I think that only works if there is a single committer, but we have 3. I suppose we could squash everything together into one commit and put all 3 of our names on it somehow?

@rcgoodfellow I merged in your changes, and then added a couple more to the PSA specification so that it uses the AsciiDoc include directive, similar to how the original used the Madoko INCLUDE directive. The only other change I made was using the[appendix] modifier for section headings that were appendices, and removing a few occurrences of "Figure", "Table", "Section", and "Appendix" before <>, since AsciiDoc adds those words automatically.

jafingerhut commented 2 weeks ago

Closing this PR in favor of https://github.com/p4lang/p4-spec/pull/1331, which has correct DCO signatures on all commits.