Addressed comments and fix include

Signed-off-by: Davide Scano <[email protected]>

Makefile

@@ -3,9 +3,10 @@ ROUGE_STYLE=github
 
 all: ${SPEC}.pdf
 
-${SPEC}.pdf: ${SPEC}.adoc 
+${SPEC}.pdf: ${SPEC}.adoc
 	time asciidoctor-pdf -v \
 		-r asciidoctor-mathematical \
+		-r asciidoctor-bibtex \
 		-a pdf-fontsdir=resources/fonts \
 		-a rouge-style=$(ROUGE_STYLE) $<
 

PNA.adoc

@@ -19,7 +19,10 @@
 :stylesdir: resources/theme/
 :stylesheet: p4-stylesheet.css
 :source-highlighter: rouge
-
+:bibtex-file: resources/theme/references.bib
+:bibtex-order: appearance
+:bibtex-style: ieee
+:listing-caption: Listing
 
 
 [abstract]
@@ -201,10 +204,8 @@ example). Note that the `main` package is not to be confused with the
 This document contains excerpts of several P4~16~ programs that use
 the `pna.p4` include file and demonstrate features of PNA. Source code
 for the complete programs can be found in the official repository
-containing the PNA specification[1].
+containing the PNA specification cite:[PNAExamplePrograms].
 
-[1]: <https://github.com/p4lang/pna> in directory `examples`.  Direct 
-    link:https://github.com/p4lang/pna/tree/main/examples[https://github.com/p4lang/pna/tree/main/examples>].
 
 [#sec-guidelines-for-portability]
 === Guidelines for Portability
@@ -313,23 +314,24 @@ from one PNA implementation to another[1].
     for different targets would be annotations on externs, etc. that
     the P4 compiler for that target needs to do its job.
 
-For each of these types, the P4 Runtime API[2] may use bit
+For each of these types, the P4 Runtime API cite:[P4RuntimeRepo] may use bit
 widths independent of the targets. These widths are defined by the P4
 Runtime API specification, and they are expected to be at least as
 large as the corresponding `InHeader_t` type below, such that they
 hold a value for any target. All PNA implementations must use data
 plane sizes for these types no wider than the corresponding
 `InHeader_t`-defined types.
 
-[2]: The P4Runtime Specification can be found here:
-    <https://p4.org/specs>
 
 [#sec-pna-type-definitions-code]
 ==== PNA type definition code excerpt 
 
-~ Begin P4Example
-[INCLUDE=pna.p4:Type_defns]
-~ End P4Example
+
+[source,p4]
+----
+include::pna.p4[tag=Type_defns]
+----
+
 
 [#sec-pna-port-types-and-values]
 ==== PNA port types and values
@@ -359,9 +361,11 @@ these statements is true:
 [#sec-pna-supported-metadata-types]
 === PNA supported metadata types
 
-~ Begin P4Example
-[INCLUDE=pna.p4:Metadata_types]
-~ End P4Example
+
+[source,p4]
+----
+include::pna.p4[tag=Metadata_types]
+----
 
 [#sec-match-kinds]
 === Match kinds
@@ -384,9 +388,11 @@ for all ingress parsers and control blocks.  The egress parser and
 control blocks can use the same types for those things, or different
 types, as the P4 program author wishes.
 
-~ Begin P4Example
-[INCLUDE=pna.p4:Programmable_blocks]
-~ End P4Example
+
+[source,p4]
+----
+include::pna.p4[tag=Programmable_blocks]
+----
 
 [#sec-packet-path-details]
 == Packet Path Details 
@@ -480,9 +486,11 @@ each occurs.
 [#sec-extern-function]
 ==== Extern function `send_to_port`
 
-~ Begin P4Example
-[INCLUDE=pna.p4:send_to_port]
-~ End P4Example
+
+[source,p4]
+----
+include::pna.p4[tag=send_to_port]
+----
 
 The extern function `send_to_port` is used to direct a packet to a
 specified network port, or to a vport.  Invoking `send_to_port(x)` is
@@ -504,9 +512,11 @@ without being looped back.
 [#sec-packet-mirroring]
 === Packet Mirroring
 
-~ Begin P4Example
-[INCLUDE=pna.p4:mirror_packet]
-~ End P4Example
+
+[source,p4]
+----
+include::pna.p4[tag=mirror_packet]
+----
 
 The extern function `mirror_packet` is used to cause a mirror copy of
 the packet currently being processed to be created.  Invoking
@@ -735,9 +745,11 @@ This section provides one example definition of a crypto acceleration engine.
 Other extern objects can be defined in future based on the functionality
 provided by the hardware accelerators.
 
-~Begin P4Example
-[INCLUDE=examples/include/crypto-accelerator.p4:Crypto_accelerator_extern_object]
-~End P4Example
+
+[source,p4]
+----
+include::examples/include/crypto-accelerator.p4[tag=Crypto_accelerator_extern_object]
+----
 
 [#sec-pna-table-properties]
 == PNA Table Properties
@@ -808,9 +820,11 @@ It is expected that PNA implementations will be able to sustain
 not be at the same packet rate supported for processing packets that
 do not call `add_entry`.
 
-~Begin P4Example
-[INCLUDE=pna.p4:add_entry_extern_function]
-~End P4Example
+
+[source,p4]
+----
+include::pna.p4[tag=add_entry_extern_function]
+----
 
 It is expected that many PNA implementations will restrict
 `add_entry()` to be called with the following restrictions:
@@ -848,9 +862,12 @@ been matched for a length of time at least its configured idle time.
 The value assigned to `pna_idle_timeout` must be a value of type
 `PNA_IdleTimeout_t`:
 
-~Begin P4Example
-[INCLUDE=pna.p4:enum_PNA_IdleTimeout_t]
-~End P4Example
+
+
+[source,p4]
+----
+include::pna.p4[tag=enum_PNA_IdleTimeout_t]
+----
 
 If the property `pna_idle_timeout` is not specified for a table, its
 default value is `NO_TIMEOUT`.  Such tables need not maintain an idle
@@ -861,10 +878,9 @@ If the property `pna_idle_timeout` is assigned a value of
 `NOTIFY_CONTROL`, the behavior is the same as defined in the Portable
 Switch Architecture if a table has its property `psa_idle_timeout`
 assigned a value of `NOTIFY_CONTROL`.  See the section titled "Table
-entry timeout notification" in the PSA specification[1].
+entry timeout notification" in the PSA specification cite:[PSA].
+
 
-[1]: The Portable Switch Architecture specification can be found here:
-    <https://p4.org/specs>
 
 If the property `pna_idle_timeout` is assigned a value of
 `AUTO_DELETE`, the behavior is similar to the behavior of the value
@@ -1024,3 +1040,7 @@ that effort.
 
 ==== From port, to port
 === Appendix: Packet ordering
+
+[bibliography]
+== References
+bibliography::references.bib[ieee]

examples/include/crypto-accelerator.p4

@@ -79,7 +79,7 @@ enum crypto_results_e {
 ///     Results: Success, Auth Failure, Hardware Error
 ///
 
-// BEGIN:Crypto_accelerator_extern_object
+// tag::Crypto_accelerator_extern_object[]
 
 extern crypto_accelerator {
     /// constructor
@@ -130,4 +130,4 @@ extern crypto_accelerator {
     // get results of the previous operation
     crypto_results_e get_results();
 }
-// END:Crypto_accelerator_extern_object
+//end::Crypto_accelerator_extern_object[]