From: Phil Sutter <phil@nwl.cc>
To: Pablo Neira Ayuso <pablo@netfilter.org>
Cc: netfilter-devel@vger.kernel.org
Subject: [nft PATCH RFC 2/2] nft.8: Make use of synopfragment in synopsis section
Date: Thu, 17 Aug 2017 15:39:00 +0200 [thread overview]
Message-ID: <20170817133900.21946-3-phil@nwl.cc> (raw)
In-Reply-To: <20170817133900.21946-1-phil@nwl.cc>
This introduces an element of indirection to list common options in
a separate place and allows to put each of the three invocation variants
onto it's own line.
Signed-off-by: Phil Sutter <phil@nwl.cc>
---
While I think readability has increased quite a bit, I don't like how
docbook formats these references: Having a name at the reference point
but not at the target is kind of unintuitive.
Another issue is that I couldn't get it to print the repeat marker
('...') inside of the brackets when referencing OPTIONS - it would end
up past the closing bracket, which appears wrong to my eye. So I used
this double indirection as one would without that repeat marker, which
didn't really improve it.
---
doc/nft.xml | 112 ++++++++++++++++++++++++++++++++++--------------------------
1 file changed, 64 insertions(+), 48 deletions(-)
diff --git a/doc/nft.xml b/doc/nft.xml
index 191a4c12f8487..2942849d8b15f 100644
--- a/doc/nft.xml
+++ b/doc/nft.xml
@@ -45,67 +45,83 @@ vi:ts=4 sw=4
<refsynopsisdiv>
<cmdsynopsis>
<command>nft</command>
- <group>
- <arg><option>-n</option></arg>
- <arg><option>--numeric</option></arg>
- </group>
- <group>
- <arg><option>-N</option></arg>
- <arg><option>--reversedns</option></arg>
- </group>
- <group>
- <arg><option>-s</option></arg>
- <arg><option>--stateless</option></arg>
- </group>
- <group>
- <arg><option>-c</option></arg>
- <arg><option>--check</option></arg>
- </group>
- <group>
- <arg><option>-a</option></arg>
- <arg><option>--handle</option></arg>
- </group>
- <group>
- <arg><option>-e</option></arg>
- <arg><option>--echo</option></arg>
+ <arg>
+ <synopfragmentref linkend="opts">OPTIONS</synopfragmentref>
+ </arg>
+ <group choice="req">
+ <arg><option>-f</option></arg>
+ <arg><option>--file</option></arg>
</group>
+ <replaceable>filename</replaceable>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>nft</command>
<arg>
- <group choice="req">
- <arg><option>-I</option></arg>
- <arg><option>--includepath</option></arg>
- </group>
- <replaceable>directory</replaceable>
+ <synopfragmentref linkend="opts">OPTIONS</synopfragmentref>
</arg>
- <group>
- <arg>
- <group choice="req">
- <arg><option>-f</option></arg>
- <arg><option>--file</option></arg>
- </group>
- <replaceable>filename</replaceable>
- </arg>
- <arg>
- <group choice="req">
- <arg><option>-i</option></arg>
- <arg><option>--interactive</option></arg>
- </group>
- </arg>
- <arg rep="repeat">
- <replaceable>cmd</replaceable>
- </arg>
+ <group choice="req">
+ <arg><option>-i</option></arg>
+ <arg><option>--interactive</option></arg>
</group>
</cmdsynopsis>
<cmdsynopsis>
<command>nft</command>
- <group>
+ <arg>
+ <synopfragmentref linkend="opts">OPTIONS</synopfragmentref>
+ </arg>
+ <arg choice="plain" rep="repeat">
+ <replaceable>cmd</replaceable>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis>
+ <command>nft</command>
+ <group choice="req">
<arg><option>-h</option></arg>
<arg><option>--help</option></arg>
- </group>
- <group>
<arg><option>-v</option></arg>
<arg><option>--version</option></arg>
</group>
</cmdsynopsis>
+ <cmdsynopsis>
+ <synopfragment id="opts">
+ <arg choice="plain" rep="repeat">
+ <synopfragmentref linkend="opt">OPTION</synopfragmentref>
+ </arg>
+ </synopfragment>
+ <synopfragment id="opt">
+ <group>
+ <arg><option>-n</option></arg>
+ <arg><option>--numeric</option></arg>
+ </group>
+ <group>
+ <arg><option>-N</option></arg>
+ <arg><option>--reversedns</option></arg>
+ </group>
+ <group>
+ <arg><option>-s</option></arg>
+ <arg><option>--stateless</option></arg>
+ </group>
+ <group>
+ <arg><option>-c</option></arg>
+ <arg><option>--check</option></arg>
+ </group>
+ <group>
+ <arg><option>-a</option></arg>
+ <arg><option>--handle</option></arg>
+ </group>
+ <group>
+ <arg><option>-e</option></arg>
+ <arg><option>--echo</option></arg>
+ </group>
+ <arg>
+ <group choice="req">
+ <arg><option>-I</option></arg>
+ <arg><option>--includepath</option></arg>
+ </group>
+ <replaceable>directory</replaceable>
+ </arg>
+ </synopfragment>
+ </cmdsynopsis>
</refsynopsisdiv>
<refsect1>
--
2.13.1
next prev parent reply other threads:[~2017-08-17 13:39 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-08-17 13:38 [nft PATCH 0/2] First attempt at synopsis fixup Phil Sutter
2017-08-17 13:38 ` [nft PATCH 1/2] nft.8: Fix and enhance synopsis section Phil Sutter
2017-08-28 16:58 ` Pablo Neira Ayuso
2017-08-28 21:25 ` Phil Sutter
2017-08-17 13:39 ` Phil Sutter [this message]
2017-08-28 16:58 ` [nft PATCH RFC 2/2] nft.8: Make use of synopfragment in " Pablo Neira Ayuso
2017-08-17 17:37 ` [nft PATCH 0/2] First attempt at synopsis fixup Phil Sutter
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170817133900.21946-3-phil@nwl.cc \
--to=phil@nwl.cc \
--cc=netfilter-devel@vger.kernel.org \
--cc=pablo@netfilter.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).