diff --git a/CONTRIBUTING b/CONTRIBUTING
index f6e3fc6..f2f8947 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 d59858c..a5266c9 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 c0b641e..643b1d4 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 b30c70b..998afe9 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 132fdc1..5dc2190 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.
