doc: support asciidoctor

Ascidoctor is a python asciidoc interpreter it has greater capabilities
than asciidoc which is a perl based interpreter.
The resulting style sheet improvements result in more professional
looking docs that can be further enhanced with our own css at some
point.
This also supports including code snippets in the documentation from the
doxygen specification files.

Signed-off-by: Mike Holmes <mike.holmes@linaro.org>
Reviewed-by: Bill Fischofer <bill.fischofer@linaro.org>

5 files changed, 20 insertions, 20 deletions

diff --git a/CONTRIBUTING b/CONTRIBUTING
index f6e3fc643..f2f894763 100644
--- a/CONTRIBUTING
+++ b/CONTRIBUTING
@@ -106,7 +106,7 @@ Code without a proper signoff cannot be merged into the mainline.
 
 5. Documenting the user docs
 ----------------------------
-- Users guides are stored in asciidoc format in the odp/docs directory and in
+- Users guides are stored in asciidoctor format in the odp/docs directory and in
   sub directories of it as appropriate.
 - ODP code references such as types and enums are highlighted using the
   + syntax. For example text referring to the type odp_pktio_t would decorate the
@@ -129,7 +129,7 @@ Code without a proper signoff cannot be merged into the mainline.
         image::../images/<image name>.svg[align="center"]
 - The images are stored in the doc/images directory as svg files.
 - Body text shall wrap at the 80 char point.
-- No warnings may be generated by the asciidoc tool.
+- No warnings may be generated by the asciidoctor tool.
 
 6. References
 -------------
diff --git a/DEPENDENCIES b/DEPENDENCIES
index d59858cbb..a5266c9e4 100644
--- a/DEPENDENCIES
+++ b/DEPENDENCIES
@@ -252,7 +252,7 @@ The tested version of doxygen is 1.8.8
 
 5.2.1 HTML
    # Debian/Ubuntu
-   $ apt-get install asciidoc source-highlight librsvg2-bin
+   $ apt-get install asciidoctor source-highlight librsvg2-bin
 
 6.0 Submitting patches
 
diff --git a/doc/Makefile.inc b/doc/Makefile.inc
index c0b641e28..643b1d4e3 100644
--- a/doc/Makefile.inc
+++ b/doc/Makefile.inc
@@ -7,6 +7,6 @@ VPATH=$(top_builddir)/doc/images
 	dot -T svg $^ -o $@
 
 .adoc.html:
-	asciidoc $(ASCIIDOC_FLAGS) --out-file=$@ $<
+	asciidoctor $(ASCIIDOC_FLAGS) --out-file=$@ $<
 
-ASCIIDOC_FLAGS =-a data-uri -b html5  -a icons -a toc2  -a max-width=55em
+ASCIIDOC_FLAGS =-a data-uri -b html5 -a icons=font -a toc2
diff --git a/doc/m4/configure.m4 b/doc/m4/configure.m4
index b30c70b18..998afe90b 100644
--- a/doc/m4/configure.m4
+++ b/doc/m4/configure.m4
@@ -7,11 +7,11 @@ if test -z "$DOXYGEN";
 fi
 
 ##########################################################################
-# Check for asciidoc availability
+# Check for asciidoctor availability
 ##########################################################################
-AC_CHECK_PROGS([ASCIIDOC], [asciidoc])
-if test -z "$ASCIIDOC";
-   then AC_MSG_WARN([asciidoc not found - continuing without asciidoc support])
+AC_CHECK_PROGS([ASCIIDOCTOR], [asciidoctor])
+if test -z "$ASCIIDOCTOR";
+   then AC_MSG_WARN([asciidoctor not found - continuing without asciidoctor support])
 fi
 
 ##########################################################################
@@ -21,8 +21,8 @@ user_guides=no
 AC_ARG_ENABLE([user-guides],
     [  --enable-user-guides    generate supplemental users guides],
     [if test "x$enableval" = "xyes"; then
-        if test -z "$ASCIIDOC";
-           then AC_MSG_ERROR([cannot generate user guides without asciidoc])
+        if test -z "$ASCIIDOCTOR";
+           then AC_MSG_ERROR([cannot generate user guides without asciidoctor])
         else
            user_guides=yes
         fi
diff --git a/doc/users-guide/users-guide-tm.adoc b/doc/users-guide/users-guide-tm.adoc
index 132fdc131..5dc2190dd 100644
--- a/doc/users-guide/users-guide-tm.adoc
+++ b/doc/users-guide/users-guide-tm.adoc
@@ -269,7 +269,7 @@ result in faster operation and/or less memory used.
 [source,c]
 ----
 
-   odp_tm_params_init(&tm_params); /* <1> */
+   odp_tm_params_init(&tm_params); // <1>
    tm_params.pktio = egress_pktio;
    tm = odp_tm_create(“Example TM”, &tm_params);
 
@@ -285,11 +285,11 @@ result in faster operation and/or less memory used.
    tmq_B2 = odp_tm_queue_create(tm, &queue_params);
    tmq_C2 = odp_tm_queue_create(tm, &queue_params);
 
-   odp_tm_node_params_init(&node_params); /* <2> */
+   odp_tm_node_params_init(&node_params); // <2>
    node_params.level = 1;
    tm_node_1 = odp_tm_node_create(tm, “TmNode1”, &node_params);
 
-   odp_tm_queue_connect(tmq_A1, tm_node_1); /* <3> */
+   odp_tm_queue_connect(tmq_A1, tm_node_1); // <3>
    odp_tm_queue_connect(tmq_B1, tm_node_1);
    odp_tm_queue_connect(tmq_A2, tm_node_1);
    odp_tm_queue_connect(tmq_B2, tm_node_1);
@@ -302,7 +302,7 @@ code does is create a scheduler PROFILE, which is effectively a registered set
 of common scheduler parameters.  NOTE that this uses some pseudocode below
 instead of real C code so as to be more concise. */
 
-   odp_tm_sched_params_init(&sched_params); /* <4> */
+   odp_tm_sched_params_init(&sched_params); // <4>
    sched_params.sched_modes = { ODP_TM_FRAME_BASED_WEIGHTS, … };
    sched_params.sched_weights = { 8, 8, 8,  … };
    sched_profile_RR = odp_tm_sched_create(“SchedProfileRR”, &sched_params);
@@ -311,24 +311,24 @@ instead of real C code so as to be more concise. */
    sched_params.sched_weights = { 8, 8, 8, … };
    sched_profile_FQ = odp_tm_sched_create(“SchedProfileFQ”, &sched_params);
 
-   odp_tm_queue_sched_config(tm_node_1, tmq_A1, sched_profile_RR); /* <5> */
+   odp_tm_queue_sched_config(tm_node_1, tmq_A1, sched_profile_RR); // <5>
    odp_tm_queue_sched_config(tm_node_1, tmq_B1, sched_profile_RR);
    odp_tm_queue_sched_config(tm_node_1, tmq_A2, sched_profile_FQ);
    odp_tm_queue_sched_config(tm_node_1, tmq_B2, sched_profile_FQ);
    odp_tm_queue_sched_config(tm_node_1, tmq_C2, sched_profile_FQ);
 
-   odp_tm_node_params_init(&node_params); /* <6> */
+   odp_tm_node_params_init(&node_params); // <6>
    node_params.level = 2;
    tm_node_2 = odp_tm_node_create(tm, “TmNode2”, &node_params);
 
-   odp_tm_node_connect(tm_node_1, tm_node_2); /* <7> */
+   odp_tm_node_connect(tm_node_1, tm_node_2); // <7>
 
-   odp_tm_sched_params_init(&sched_params); /* <8> */
+   odp_tm_sched_params_init(&sched_params); // <8>
    sched_params.sched_modes = { ODP_TM_BYTE_BASED_WEIGHTS, … };
    sched_params.sched_weights = { 8, 16, 24,  … };
    sched_profile_WFQ = odp_tm_sched_create(“SchedProfileWFQ”, &sched_params);
 
-   odp_tm_node_sched_config(tm_node_2, tm_node_1, sched_profile_WFQ); /* <9> */
+   odp_tm_node_sched_config(tm_node_2, tm_node_1, sched_profile_WFQ); // <9>
 ----
 
 <1> Create a tm system, since that is a precursor to creating tm_queues.