[nft PATCH 0/2] First attempt at synopsis fixup

[nft PATCH 0/2] First attempt at synopsis fixup

[Phil Sutter]

The first patch is to be considered a fix and optimization, the second
one is rather experimental and I would like to hear your thoughts about
it (some details as to why I'm not happy with it can be found below it's
commit message).

Phil Sutter (2):
  nft.8: Fix and enhance synopsis section
  nft.8: Make use of synopfragment in synopsis section

 doc/nft.xml | 98 +++++++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 70 insertions(+), 28 deletions(-)

-- 
2.13.1

[nft PATCH 1/2] nft.8: Fix and enhance synopsis section

[Phil Sutter]

This patch addresses shortcomings in the main synopsis section
illustrating possible invocations of nft command:

- Fix font styles to correctly put options into bold font and meta
  characters (brackets, pipes) into normal font.

- Add missing options to synopsis line.

- Use curly braces where either one of the alternatives is required.

- Remove choice="opt" attribute since that is the default anyway.

- Note that --includepath option is allowed to be given multiple times.

Signed-off-by: Phil Sutter <phil@nwl.cc>
---
 doc/nft.xml | 74 +++++++++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 50 insertions(+), 24 deletions(-)

diff --git a/doc/nft.xml b/doc/nft.xml
index d7aae3f03b8c1..191a4c12f8487 100644
--- a/doc/nft.xml
+++ b/doc/nft.xml
@@ -45,40 +45,66 @@ vi:ts=4 sw=4
 	<refsynopsisdiv>
 		<cmdsynopsis>
 			<command>nft</command>
-			<arg choice="opt">
-				<option>-n | --numeric</option>
-			</arg>
-			<arg choice="opt">
-				<option>-s | --stateless</option>
-			</arg>
-			<arg choice="opt">
-				<option>-c | --check</option>
-			</arg>
-			<arg choice="opt">
-				<option>[-I | --includepath]</option>
+			<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>
 			<group>
-				<arg choice="opt">
-					<option>[-f | --file]</option>
+				<arg>
+					<group choice="req">
+						<arg><option>-f</option></arg>
+						<arg><option>--file</option></arg>
+					</group>
 					<replaceable>filename</replaceable>
 				</arg>
-				<arg choice="opt">
-					<option>[-i | --interactive]</option>
+				<arg>
+					<group choice="req">
+						<arg><option>-i</option></arg>
+						<arg><option>--interactive</option></arg>
+					</group>
 				</arg>
-				<arg choice="opt" rep="repeat">
+				<arg rep="repeat">
 					<replaceable>cmd</replaceable>
 				</arg>
 			</group>
 		</cmdsynopsis>
 		<cmdsynopsis>
 			<command>nft</command>
-			<arg choice="opt">
-				<option>-h | --help</option>
-			</arg>
-			<arg choice="opt">
-				<option>-v | --version</option>
-			</arg>
+			<group>
+				<arg><option>-h</option></arg>
+				<arg><option>--help</option></arg>
+			</group>
+			<group>
+				<arg><option>-v</option></arg>
+				<arg><option>--version</option></arg>
+			</group>
 		</cmdsynopsis>
 	</refsynopsisdiv>
 
@@ -141,7 +167,7 @@ vi:ts=4 sw=4
 				</listitem>
 			</varlistentry>
 			<varlistentry>
-				<term><option>-N</option></term>
+				<term><option>-N, --reversedns</option></term>
 				<listitem>
 					<para>
 						Translate IP addresses to names. Usually requires network traffic for DNS lookup.
@@ -170,7 +196,7 @@ vi:ts=4 sw=4
 				<term><option>-I, --includepath <replaceable>directory</replaceable></option></term>
 				<listitem>
 					<para>
-						Add the directory <replaceable>directory</replaceable> to the list of directories to be searched for included files.
+						Add the directory <replaceable>directory</replaceable> to the list of directories to be searched for included files. This option may be specified multiple times.
 					</para>
 				</listitem>
 			</varlistentry>
-- 
2.13.1

[nft PATCH RFC 2/2] nft.8: Make use of synopfragment in synopsis section

[Phil Sutter]

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

Re: [nft PATCH 0/2] First attempt at synopsis fixup

[Phil Sutter]

On Thu, Aug 17, 2017 at 03:38:58PM +0200, Phil Sutter wrote:
> The first patch is to be considered a fix and optimization, the second
> one is rather experimental and I would like to hear your thoughts about
> it (some details as to why I'm not happy with it can be found below it's
> commit message).

Since I assume nobody likes to apply the patches individually and
compile the sources just to see the difference in man page output, here
are two screen shots:

After first patch (only font style fix):
http://nwl.cc/~n0-1/nft.8_style_fix.png
(No idea how one could add hints for better spots to break long lines.)

After the second one (with added indirections):
http://nwl.cc/~n0-1/nft.8_indirection.png

Cheers, Phil

Re: [nft PATCH RFC 2/2] nft.8: Make use of synopfragment in synopsis section

[Pablo Neira Ayuso]

On Thu, Aug 17, 2017 at 03:39:00PM +0200, Phil Sutter wrote:
> 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.

Feel free to send a patch to convert this to use a more orthodox
markup language for manpages.

Re: [nft PATCH 1/2] nft.8: Fix and enhance synopsis section

[Pablo Neira Ayuso]

On Thu, Aug 17, 2017 at 03:38:59PM +0200, Phil Sutter wrote:
> This patch addresses shortcomings in the main synopsis section
> illustrating possible invocations of nft command:
> 
> - Fix font styles to correctly put options into bold font and meta
>   characters (brackets, pipes) into normal font.
> 
> - Add missing options to synopsis line.
> 
> - Use curly braces where either one of the alternatives is required.
> 
> - Remove choice="opt" attribute since that is the default anyway.
> 
> - Note that --includepath option is allowed to be given multiple times.

I'm going to apply this.

I'm undecided with 2/2, I don't remember to have seen such
indirections in other manpages?

Thanks.

Re: [nft PATCH 1/2] nft.8: Fix and enhance synopsis section

[Phil Sutter]

Hi Pablo,

On Mon, Aug 28, 2017 at 06:58:53PM +0200, Pablo Neira Ayuso wrote:
> On Thu, Aug 17, 2017 at 03:38:59PM +0200, Phil Sutter wrote:
> > This patch addresses shortcomings in the main synopsis section
> > illustrating possible invocations of nft command:
> > 
> > - Fix font styles to correctly put options into bold font and meta
> >   characters (brackets, pipes) into normal font.
> > 
> > - Add missing options to synopsis line.
> > 
> > - Use curly braces where either one of the alternatives is required.
> > 
> > - Remove choice="opt" attribute since that is the default anyway.
> > 
> > - Note that --includepath option is allowed to be given multiple times.
> 
> I'm going to apply this.

Thanks!

> I'm undecided with 2/2,

>From my side, this is according to (the hidden) plan. :)

> I don't remember to have seen such indirections in other manpages?

>From iproute2 (as said, I'm biased), I'm used to stuff like this:
	
| nft [ OPTIONS ] ...
|
| OPTIONS := [ OPTIONS ] OPTION
| OPTION := [ -a | -e | -n ]

Maybe for others it's more of an obstacle to parse this recursive style,
it really seems intuitive to me at least. And it's a quite efficient way
to define the syntax in a very precise manner.

Of course it's nice to have some layer of abstraction to allow for
formatting into other markups, like HTML for example. So I'll have a
look at alternatives which will keep that flexibility yet allow for the
style I prefer (unless you consider it not much more readable than what
docbook offers).

Thanks, Phil