Switching from Madoko to AsciiDoc for PNA specification #128
Conversation
Signed-off-by: Davide Scano <[email protected]>
Signed-off-by: Davide Scano <[email protected]>
Signed-off-by: Davide Scano <[email protected]>
|
Please ping me when you believe this is ready to go. It looks like there are still work on tables to be done, and probably some other things. |
|
I propose using NOTE to replace Begin/End TBD |
Sounds reasonable to me. Go for it, and we can take a look at the PDF results, but I'd be surprised if there is any problem with the idea. |
Signed-off-by: Davide Scano <[email protected]>
|
@jafingerhut I have finished converting PNA specification from Madoko to AsciiDoc.
|
|
There are two sections in the table of contents named "Revision history". Ideally there should be only one, which should be the first appendix. |
|
The current Madoko PDF has appendices A, B, C, etc. As of the time of writing this comment, the AsciiDoc PDF has one appendix, A, with separate sub-sections for each of what were appendices A, B, C, ... If it is straightforward to make the AsciiDoc appendices be more like the original Madoko ones, that would be nice. I believe it is possible, as I think we did this for the P4 language spec AsciiDoc. |
PNA.adoc
Outdated
| P4~16~ externs (e.g., counters, meters, and registers). | ||
|
|
||
| PNA is designed to model the common features of a broad class of NIC | ||
| devices. By providing standard APIs and coding guidelines, the hope is | ||
| to enable developers to write programs that are portable across | ||
| multiple NIC devices that are conformant to the PNA[^PNAPortability]. | ||
| multiple NIC devices that are conformant to the PNA[1]. |
There was a problem hiding this comment.
Insert whitespace before [1].
There was a problem hiding this comment.
We might also want to use different text than [1], since there are also auto-generated bibliography references that look like [1], too. Maybe [Footnote 1], both where it is referenced from, and where the footnote is shown?
PNA.adoc
Outdated
| target specific `pna.p4` include file. They are expected to differ | ||
| from one PNA implementation to another[^PNAP4TargetSpecific]. | ||
| from one PNA implementation to another[1]. |
There was a problem hiding this comment.
I would recommend [Footnote 2] here, to avoid duplication with the earlier [Footnote 1].
Signed-off-by: Dscano <[email protected]>
|
Thanks for updating the section headings in the appendices. I would recommend removing the word "Appendix" from the AsciiDoc source for the titles of those appendices, because as of commit 5, the generated PDF output has titles like these for the appendices:
I believe the |
Signed-off-by: Dscano <[email protected]>
| build/${SPEC}.pdf: ${SPEC}.mdk | ||
| madoko --pdf -vv --png --odir=build $< | ||
|
|
||
| build/${SPEC}.pdf: p4.json |
There was a problem hiding this comment.
I believe the p4.json file should be removed with this PR, unless you find some reference to that file in the files that remain. I think p4.json was only used for Madoko syntax highlighting.
Makefile
Outdated
|
|
||
| build/${SPEC}.pdf: p4.json | ||
| build/${SPEC}.pdf: pna.p4 | ||
| ${SPEC}.pdf: ${SPEC}.adoc |
There was a problem hiding this comment.
Please add the file pna.p4 as a dependency on this rule, and the rule for generating HTML output, since PNA.adoc has include directives that include portions of pna.p4. If pna.p4 changes, it is likely that the PDF and/or HTML files need to be updated, too.
There was a problem hiding this comment.
Also, please add a Makefile rule to generate HTML output. I don't see one here. It would be helpful to have that, even if the original Makefile did not have such a rule to generate HTML from Madoko source.
Signed-off-by: Dscano <[email protected]>
Signed-off-by: Dscano <[email protected]>
|
I will wait to merge this after mentioning this change at the next arch work group meeting on 2024-Jan-13. |
I am currently transitioning the PNA specification from Madoko to AsciiDoc. This is the first PR to initiate the work.