From mboxrd@z Thu Jan 1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
by inbox.dpdk.org (Postfix) with ESMTP id 602D043CE3;
Mon, 18 Mar 2024 12:21:41 +0100 (CET)
Received: from mails.dpdk.org (localhost [127.0.0.1])
by mails.dpdk.org (Postfix) with ESMTP id 3196E40DDD;
Mon, 18 Mar 2024 12:21:11 +0100 (CET)
Received: from szxga04-in.huawei.com (szxga04-in.huawei.com [45.249.212.190])
by mails.dpdk.org (Postfix) with ESMTP id 4B99D40A6B
for <dev@dpdk.org>; Mon, 18 Mar 2024 12:21:01 +0100 (CET)
Received: from mail.maildlp.com (unknown [172.19.162.112])
by szxga04-in.huawei.com (SkyGuard) with ESMTP id 4TysmN06yDz2BgZL;
Mon, 18 Mar 2024 19:18:28 +0800 (CST)
Received: from dggpeml500024.china.huawei.com (unknown [7.185.36.10])
by mail.maildlp.com (Postfix) with ESMTPS id B08D7140153;
Mon, 18 Mar 2024 19:20:59 +0800 (CST)
Received: from localhost.localdomain (10.50.165.33) by
dggpeml500024.china.huawei.com (7.185.36.10) with Microsoft SMTP Server
(version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id
15.1.2507.35; Mon, 18 Mar 2024 19:20:59 +0800
From: Chengwen Feng <fengchengwen@huawei.com>
To: <thomas@monjalon.net>, <david.marchand@redhat.com>
CC: <dev@dpdk.org>
Subject: [PATCH v4 6/6] argparse: fix doc don't display two hyphens
Date: Mon, 18 Mar 2024 11:18:38 +0000
Message-ID: <20240318111838.16991-7-fengchengwen@huawei.com>
X-Mailer: git-send-email 2.17.1
In-Reply-To: <20240318111838.16991-1-fengchengwen@huawei.com>
References: <20240220131502.47510-1-fengchengwen@huawei.com>
<20240318111838.16991-1-fengchengwen@huawei.com>
MIME-Version: 1.0
Content-Type: text/plain
X-Originating-IP: [10.50.165.33]
X-ClientProxiedBy: dggems704-chm.china.huawei.com (10.3.19.181) To
dggpeml500024.china.huawei.com (7.185.36.10)
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
<mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
<mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
With the line in rst file:
The single mode: "--aaa" or "-a".
corresponding line in html doc:
The single mode: -aaa or -a.
the two hyphens (--aaa) become one (-aaa).
According to [1], this commit uses the backquote (``xxx``) to fix it.
And for consistency, use this format for all arguments.
Fixes: e3e579f5bab5 ("argparse: introduce argparse library")
[1] https://stackoverflow.com/questions/51075907/display-two-dashes-in-rst-file
Signed-off-by: Chengwen Feng <fengchengwen@huawei.com>
---
doc/guides/prog_guide/argparse_lib.rst | 47 +++++++++++++-------------
lib/argparse/rte_argparse.h | 4 +--
2 files changed, 26 insertions(+), 25 deletions(-)
diff --git a/doc/guides/prog_guide/argparse_lib.rst b/doc/guides/prog_guide/argparse_lib.rst
index a6ac11b1c0..f827312daa 100644
--- a/doc/guides/prog_guide/argparse_lib.rst
+++ b/doc/guides/prog_guide/argparse_lib.rst
@@ -90,9 +90,9 @@ The following code demonstrates how to use:
}
In this example, the arguments which start with a hyphen (-) are optional
-arguments (they're "--aaa"/"--bbb"/"--ccc"/"--ddd"/"--eee"/"--fff"); and the
-arguments which don't start with a hyphen (-) are positional arguments
-(they're "ooo"/"ppp").
+arguments (they're ``--aaa``/``--bbb``/``--ccc``/``--ddd``/``--eee``/``--fff``);
+and the arguments which don't start with a hyphen (-) are positional arguments
+(they're ``ooo``/``ppp``).
Every argument must be set whether to carry a value (one of
``RTE_ARGPARSE_ARG_NO_VALUE``, ``RTE_ARGPARSE_ARG_REQUIRED_VALUE`` and
@@ -106,23 +106,23 @@ User Input Requirements
~~~~~~~~~~~~~~~~~~~~~~~
For optional arguments which take no-value,
-the following mode is supported (take above "--aaa" as an example):
+the following mode is supported (take above ``--aaa`` as an example):
-- The single mode: "--aaa" or "-a".
+- The single mode: ``--aaa`` or ``-a``.
For optional arguments which take required-value,
-the following two modes are supported (take above "--bbb" as an example):
+the following two modes are supported (take above ``--bbb`` as an example):
-- The kv mode: "--bbb=1234" or "-b=1234".
+- The kv mode: ``--bbb=1234`` or ``-b=1234``.
-- The split mode: "--bbb 1234" or "-b 1234".
+- The split mode: ``--bbb 1234`` or ``-b 1234``.
For optional arguments which take optional-value,
-the following two modes are supported (take above "--ccc" as an example):
+the following two modes are supported (take above ``--ccc`` as an example):
-- The single mode: "--ccc" or "-c".
+- The single mode: ``--ccc`` or ``-c``.
-- The kv mode: "--ccc=123" or "-c=123".
+- The kv mode: ``--ccc=123`` or ``-c=123``.
For positional arguments which must take required-value,
their values are parsing in the order defined.
@@ -130,7 +130,7 @@ their values are parsing in the order defined.
.. note::
The compact mode is not supported.
- Take above "-a" and "-d" as an example, don't support "-ad" input.
+ Take above ``-a`` and ``-d`` as an example, don't support ``-ad`` input.
Parsing by autosave way
~~~~~~~~~~~~~~~~~~~~~~~
@@ -139,23 +139,23 @@ Argument of known value type (e.g. ``RTE_ARGPARSE_ARG_VALUE_INT``)
could be parsed using this autosave way,
and its result will save in the ``val_saver`` field.
-In the above example, the arguments "--aaa"/"--bbb"/"--ccc" and "ooo"
+In the above example, the arguments ``--aaa``/``--bbb``/``--ccc`` and ``ooo``
both use this way, the parsing is as follows:
-- For argument "--aaa", it is configured as no-value,
+- For argument ``--aaa``, it is configured as no-value,
so the ``aaa_val`` will be set to ``val_set`` field
which is 100 in the above example.
-- For argument "--bbb", it is configured as required-value,
+- For argument ``--bbb``, it is configured as required-value,
so the ``bbb_val`` will be set to user input's value
- (e.g. will be set to 1234 with input "--bbb 1234").
+ (e.g. will be set to 1234 with input ``--bbb 1234``).
-- For argument "--ccc", it is configured as optional-value,
- if user only input "--ccc" then the ``ccc_val`` will be set to ``val_set`` field
- which is 200 in the above example;
- if user input "--ccc=123", then the ``ccc_val`` will be set to 123.
+- For argument ``--ccc``, it is configured as optional-value,
+ if user only input ``--ccc`` then the ``ccc_val`` will be set to ``val_set``
+ field which is 200 in the above example;
+ if user input ``--ccc=123``, then the ``ccc_val`` will be set to 123.
-- For argument "ooo", it is positional argument,
+- For argument ``ooo``, it is positional argument,
the ``ooo_val`` will be set to user input's value.
Parsing by callback way
@@ -165,7 +165,8 @@ It could also choose to use callback to parse,
just define a unique index for the argument
and make the ``val_save`` field to be NULL also zero value-type.
-In the above example, the arguments "--ddd"/"--eee"/"--fff" and "ppp" both use this way.
+In the above example, the arguments ``--ddd``/``--eee``/``--fff`` and ``ppp``
+both use this way.
Multiple times argument
~~~~~~~~~~~~~~~~~~~~~~~
@@ -178,7 +179,7 @@ For example:
{ "--xyz", "-x", "xyz argument", NULL, (void *)10, RTE_ARGPARSE_ARG_REQUIRED_VALUE | RTE_ARGPARSE_ARG_SUPPORT_MULTI },
-Then the user input could contain multiple "--xyz" arguments.
+Then the user input could contain multiple ``--xyz`` arguments.
.. note::
diff --git a/lib/argparse/rte_argparse.h b/lib/argparse/rte_argparse.h
index 98ad9971ea..b6b016e388 100644
--- a/lib/argparse/rte_argparse.h
+++ b/lib/argparse/rte_argparse.h
@@ -83,8 +83,8 @@ extern "C" {
struct rte_argparse_arg {
/**
* Long name of the argument:
- * 1) If the argument is optional, it must start with '--'.
- * 2) If the argument is positional, it must not start with '-'.
+ * 1) If the argument is optional, it must start with ``--``.
+ * 2) If the argument is positional, it must not start with ``-``.
* 3) Other case will be considered as error.
*/
const char *name_long;
--
2.17.1