From patchwork Wed May 4 17:04:12 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Mike Holmes X-Patchwork-Id: 67163 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp299874qge; Wed, 4 May 2016 10:04:54 -0700 (PDT) X-Received: by 10.140.249.87 with SMTP id u84mr10000573qhc.80.1462381494094; Wed, 04 May 2016 10:04:54 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id c103si712817qkh.73.2016.05.04.10.04.53; Wed, 04 May 2016 10:04:54 -0700 (PDT) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 7B2D3615CC; Wed, 4 May 2016 17:04:53 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: X-Spam-Status: No, score=-2.6 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2, URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id BDA5A6156D; Wed, 4 May 2016 17:04:46 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 31030615BD; Wed, 4 May 2016 17:04:44 +0000 (UTC) Received: from mail-qg0-f53.google.com (mail-qg0-f53.google.com [209.85.192.53]) by lists.linaro.org (Postfix) with ESMTPS id 4E5F8611FE for ; Wed, 4 May 2016 17:04:43 +0000 (UTC) Received: by mail-qg0-f53.google.com with SMTP id f74so26664013qge.2 for ; Wed, 04 May 2016 10:04:43 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=dYnTPhZEmONXcoqt7mstD9p79GZ347pre7vTLmUevSM=; b=A48Z3HPMrn0VSueqsF3TMeFBlXw1YPN4Dh2ZLg8VDvQ462lrcWTl9gM5vgxj6rvZYH bj+7ojIC6vBwDdZayWww1VqFl3OADLCNL4XSiBtbKzghU69Ju76MFZxiESbfhCVRsnly EnPKVwjM/J2fcT1Ju+7MI9CHNxDtJEYj9pFx9P3k2LMbtPye8ykh4RX71OSZ8eIkbDsJ mr6gXcEWEkwSmGY+4MJ0Hh7SYLV3ehv9WKiGulrwQPXqTmiQf4BG6PfXmRDISUwh/Ri7 0MSthApFhM0wdG9tsXeHmOMnP6uV7cOgc62nGU361UXc9euOF/6FmEtoy8sbXe0EfPFv ZDyg== X-Gm-Message-State: AOPr4FWhiHMwsWGS37TC5sNY/wf8K/rS8EZSD0jtv6Vx5d0Z6wluoFn2RuhViE7BuKQbqhH5M94= X-Received: by 10.140.29.246 with SMTP id b109mr9374827qgb.2.1462381482980; Wed, 04 May 2016 10:04:42 -0700 (PDT) Received: from localhost.localdomain (c-98-221-136-245.hsd1.nj.comcast.net. [98.221.136.245]) by smtp.gmail.com with ESMTPSA id b18sm1663994qkc.9.2016.05.04.10.04.42 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 04 May 2016 10:04:42 -0700 (PDT) From: Mike Holmes To: lng-odp@lists.linaro.org Date: Wed, 4 May 2016 13:04:12 -0400 Message-Id: <1462381452-11960-1-git-send-email-mike.holmes@linaro.org> X-Mailer: git-send-email 2.7.4 MIME-Version: 1.0 X-Topics: patch Subject: [lng-odp] [PATCH v2] doc: support ascidoctor X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" 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 Reviewed-by: Bill Fischofer --- CONTRIBUTING | 4 ++-- DEPENDENCIES | 2 +- doc/Makefile.inc | 4 ++-- doc/m4/configure.m4 | 12 ++++++------ doc/users-guide/users-guide-tm.adoc | 18 +++++++++--------- 5 files changed, 20 insertions(+), 20 deletions(-) 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/.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.