Improvement of manpages clvmd.8 and blkdeactivate.8

Improvement of manpages clvmd.8 and blkdeactivate.8

[saulery]

Hello,

Here is a much improved version of blkdeactivate.8 clvmd.8 and manpages. I can
update others in the same way if you're interested.

Regards,

-- 
St?phane Aulery

Improve clvmd.8 manpage and help output

[saulery]

From: St?phane Aulery <saulery@free.fr>

- closer to the recommendation of man-pages (7) if possible
- Add crossrefs
- Sort options and crossrefs
- Fix default timeout (60 secs) of -t
- Fix ambiguities in the use of spaces before values
- Documents -I[auto]

Signed-off-by: St?phane Aulery <saulery@free.fr>
---
 daemons/clvmd/clvmd.c |  16 +++---
 man/clvmd.8.in        | 140 +++++++++++++++++++++++++-------------------------
 2 files changed, 78 insertions(+), 78 deletions(-)

diff --git a/daemons/clvmd/clvmd.c b/daemons/clvmd/clvmd.c
index 0c1cb44..5cd6874 100644
--- a/daemons/clvmd/clvmd.c
+++ b/daemons/clvmd/clvmd.c
@@ -153,16 +153,11 @@ static if_type_t get_cluster_type(void);
 static void usage(const char *prog, FILE *file)
 {
 	fprintf(file, "Usage: %s [options]\n"
-		"   -V       Show version of clvmd\n"
-		"   -h       Show this help information\n"
+		"   -C       Sets debug level (from -d) on all clvmd instances clusterwide\n"
 		"   -d[n]    Set debug logging (0:none, 1:stderr (implies -f option), 2:syslog)\n"
+		"   -E<uuid> Take this lock uuid as exclusively locked resource (for restart)\n"
 		"   -f       Don't fork, run in the foreground\n"
-		"   -E<lockuuid> Take this lock uuid as exclusively locked resource (for restart)\n"
-		"   -R       Tell all running clvmds in the cluster to reload their device cache\n"
-		"   -S       Restart clvmd, preserving exclusive locks\n"
-		"   -C       Sets debug level (from -d) on all clvmd instances clusterwide\n"
-		"   -t<secs> Command timeout (default 60 seconds)\n"
-		"   -T<secs> Startup timeout (default none)\n"
+		"   -h       Show this help information\n"
 		"   -I<cmgr> Cluster manager (default: auto)\n"
 		"            Available cluster managers: "
 #ifdef USE_COROSYNC
@@ -177,6 +172,11 @@ static void usage(const char *prog, FILE *file)
 #ifdef USE_SINGLENODE
 		"singlenode "
 #endif
+		"   -R       Tell all running clvmds in the cluster to reload their device cache\n"
+		"   -S       Restart clvmd, preserving exclusive locks\n"
+		"   -t<secs> Command timeout (default: 60 seconds)\n"
+		"   -T<secs> Startup timeout (default:  0 seconds)\n"
+		"   -V       Show version of clvmd\n"
 		"\n", prog);
 }
 
diff --git a/man/clvmd.8.in b/man/clvmd.8.in
index d79c29b..d94d920 100644
--- a/man/clvmd.8.in
+++ b/man/clvmd.8.in
@@ -3,62 +3,55 @@
 clvmd \(em cluster LVM daemon
 .SH SYNOPSIS
 .B clvmd
-.RB [ \-d
-.RI [< value >]
-.RB [ \-C ]]
-.RB [ \-E
-.RI < "lock uuid" >]
+.RB [
+.RB [ \-C ]
+.RB [ \-d [< \fIvalue\fP >]
+.RB ]
+.RB [ \-E < "\fIlock uuid\fP" >]
 .RB [ \-f ]
 .RB [ \-h ]
-.RB [ \-I
-.IR "cluster_manager" ]
+.RB [ \-I < "\fIcluster manager\fP" >]
 .RB [ \-R ]
 .RB [ \-S ]
-.RB [ \-t
-.RI < timeout >]
-.RB [ \-T
-.RI < "start timeout" >]
+.RB [ \-t < "\fItimeout\fP" >]
+.RB [ \-T < "\fIstart timeout\fP" >]
 .RB [ \-V ]
 .SH DESCRIPTION
-clvmd is the daemon that distributes LVM metadata updates around a cluster.
-It must be running on all nodes in the cluster and will give an error
-if a node in the cluster does not have this daemon running.
+.B Clvmd
+is the daemon that distributes LVM metadata updates around a cluster. It
+must be running on all nodes in the cluster and will give an error if a node
+in the cluster does not have this daemon running.
 .SH OPTIONS
 .TP
-.BR \-d [< \fIvalue >]
-Enable debug logging. Value can be 0, 1 or 2.
-.br
-0 disables debug logging
+.B \-C
+Sets debug level on all \fBclvmd\fP instances clusterwide (Only valid if
+\fB\-d\fP is also specified). Tells all instances of \fBclvmd\fP in a
+cluster to enable/disable debug logging. Without this switch, only the local
+\fBclvmd\fP will change its debug level to that given with \fB\-d\fP.
+
+This does not work correctly if specified on the command-line that starts
+\fBclvmd\fP. If you want to start a new instance \fBand\fP enable cluster-wide
+logging then the command needs to be issued twice, eg:
 .br
-1 sends debug logs to stderr (implies \fB\-f\fP option)
+.B clvmd
 .br
-2 sends debug logs to syslog
+.B clvmd \-d2
 .br
-If
-.B \-d
-is specified without a value then 1 is assumed.
 .TP
-.B \-C
-Only valid if
-.B \-d
-is also specified. Tells all clvmds in a cluster to enable/disable debug logging.
-Without this switch, only the local clvmd will change its debug level to that
-given with
-.B \-d
-.
+.BR "\-d" "[<" "\fIvalue\fP" ">]"
+Set debug logging level. \fIValue\fP can be:
 .br
-This does not work correctly if specified on the command-line that starts clvmd.
-If you want to start clvmd
-.B and
-enable cluster-wide logging then the command needs to be issued twice, eg:
+0: disabled;
 .br
-.B clvmd
+1: sends debug logs to stderr (implies \fB\-f\fP);
 .br
-.B clvmd \-d2
+2: sends debug logs to
+.BR syslog "(3).
 .br
+If \fB\-d\fP is specified without a \fIvalue\fP then 1 is assumed.
 .TP
-.BR \-E < "\fIlock uuid" >
-Pass lock uuid to be reacquired exclusively when clvmd is restarted.
+.BR "\-E" "<" "\fIlock uuid\fP" ">"
+Pass \fIlock uuid\fP to be reacquired exclusively when \fBclvmd\fP is restarted.
 .TP
 .B \-f
 Don't fork, run in the foreground.
@@ -66,48 +59,52 @@ Don't fork, run in the foreground.
 .B \-h
 Show help information.
 .TP
-.B \-I \fIcluster manager
-Selects the cluster manager to use for locking and internal communications,
-the available managers will be listed as part of the \fBclvmd \-h\fP output.
-clvmd will use the first cluster manager that succeeds, and it checks them
-in the order cman,corosync,openais. As it is quite possible to have
-(eg) corosync and cman available on the same system you might have to
-manually specify this option to override the search.
+.BR "\-I" "<" "\fIcluster manager\fP" ">"
+Selects the \fIcluster manager\fP to use for locking and internal
+communications. As it is quite possible to have multiple managers available on
+the same system you might have to manually specify this option to override the
+search.
+
+By default, omit \fB-I\fP is equivalent to \fB\-I\fP\fIauto\fP. \fBClvmd\fP
+will use the first cluster manager that succeeds, and it checks them in a
+predefined order. The available managers will be listed by order as part of the
+\fBclvmd \-h\fP output.
 .TP
 .B \-R
-Tells all the running clvmds in the cluster to reload their device cache and
-re-read the lvm configuration file. This command should be run whenever the
+Tells all the running instance of \fBclvmd\fP in the cluster to reload their device cache and
+re-read the lvm configuration file \fBlvm.conf\fP(5). This command should be run whenever the
 devices on a cluster system are changed.
 .TP
 .B \-S
-Tells the running clvmd to exit and reexecute itself, for example at the
-end of a package upgrade.  The new instance is instructed to reacquire
-any locks in the same state as they were previously held.  (Alternative
+Tells the running \fBclvmd\fP to exit and reexecute itself, for example at the
+end of a package upgrade. The new instance is instructed to reacquire
+any locks in the same state as they were previously held. (Alternative
 methods of restarting the daemon have the side effect of changing
 exclusive LV locks into shared locks.)
 .TP
-.BR \-t < \fItimeout >
-Specifies the timeout for commands to run around the cluster. This should not
+.BR "\-t" "<" "\fItimeout\fP" ">"
+Specifies the \fItimeout\fP for commands to run around the cluster. This should not
 be so small that commands with many disk updates to do will fail, so you
 may need to increase this on systems with very large disk farms.
-The default is 30 seconds.
+The default is 60 seconds.
 .TP
-.BR \-T < "\fIstart timeout" >
-Specifies the timeout for clvmd daemon startup. If the daemon does not report
-that it has started up within this time then the parent command will exit with
-status of 5. This does NOT mean that clvmd has not started! What it means is
-that the startup of clvmd has been delayed for some reason; the most likely
-cause of this is an inquorate cluster though it could be due to locking
-latencies on a cluster with large numbers of logical volumes. If you get the
-return code of 5 it is usually not necessary to restart clvmd - it will start
-as soon as that blockage has cleared. This flag is to allow startup scripts
-to exit in a timely fashion even if the cluster is stalled for some reason.
-.br
+.BR "\-T" "<" "\fIstart timeout\fP" ">"
+Specifies the \fIstart timeout\fP for \fBclvmd\fP daemon startup. If the
+daemon does not report that it has started up within this time then the parent
+command will exit with status of 5. This does NOT mean that \fBclvmd\fP has
+not started! What it means is that the startup has been delayed for some
+reason; the most likely cause of this is an inquorate cluster though it
+could be due to locking latencies on a cluster with large numbers of logical
+volumes. If you get the return code of 5 it is usually not necessary to
+restart \fBclvmd\fP ? it will start as soon as that blockage has cleared.
+This flag is to allow startup scripts to exit in a timely fashion even if the
+cluster is stalled for some reason.
+
 The default is 0 (no timeout) and the value is in seconds. Don't set this too
 small or you will experience spurious errors. 10 or 20 seconds might be
 sensible.
-.br
-This timeout will be ignored if you start clvmd with the \-d switch.
+
+This timeout will be ignored if you start \fBclvmd\fP with the \fB\-d\fP.
 .TP
 .B \-V
 Display the version of the cluster LVM daemon.
@@ -115,11 +112,14 @@ Display the version of the cluster LVM daemon.
 .SH ENVIRONMENT VARIABLES
 .TP
 .B LVM_CLVMD_BINARY
-The CLVMD binary to use when clmvd restart is requested.
+The CLVMD binary to use when \fBclmvd\fP restart is requested.
 Defaults to #CLVMD_PATH#.
 .TP
 .B LVM_BINARY
-The LVM2 binary to use. Defaults to #LVM_PATH#.
+The LVM2 binary to use.
+Defaults to #LVM_PATH#.
 
 .SH SEE ALSO
-.BR lvm (8)
+.BR syslog (3),
+.BR lvm.conf (5),
+.BR lvm (8).
-- 
2.1.3

Improve clvmd.8 manpage and help output

[saulery]

From: St?phane Aulery <saulery@free.fr>

Closer to the recommendation of groff_man (7) if possible

Signed-off-by: St?phane Aulery <saulery@free.fr>
---
 man/clvmd.8.in | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/man/clvmd.8.in b/man/clvmd.8.in
index d94d920..f639194 100644
--- a/man/clvmd.8.in
+++ b/man/clvmd.8.in
@@ -39,16 +39,16 @@ logging then the command needs to be issued twice, eg:
 .br
 .TP
 .BR "\-d" "[<" "\fIvalue\fP" ">]"
-Set debug logging level. \fIValue\fP can be:
-.br
-0: disabled;
-.br
-1: sends debug logs to stderr (implies \fB\-f\fP);
-.br
-2: sends debug logs to
-.BR syslog "(3).
-.br
-If \fB\-d\fP is specified without a \fIvalue\fP then 1 is assumed.
+Set debug logging level.If \fB\-d\fP is specified without a \fIvalue\fP then 1
+is assumed. \fIValue\fP can be:
+.RS
+.IP \fI0\fP
+Disabled;
+.IP \fI1\fP
+Sends debug logs to stderr (implies \fB\-f\fP);
+.IP \fI2\fP
+Sends debug logs to \fBsyslog\fP(3).
+.RE
 .TP
 .BR "\-E" "<" "\fIlock uuid\fP" ">"
 Pass \fIlock uuid\fP to be reacquired exclusively when \fBclvmd\fP is restarted.
-- 
2.1.3

Improve blkdeactivate.8 manpage and help output

[saulery]

From: St?phane Aulery <saulery@free.fr>

- Closer to the recommendation of man-pages and groff_man (7) if possible
- Sort options and crossrefs
- Relocate sub-options on the right places

Signed-off-by: St?phane Aulery <saulery@free.fr>
---
 man/blkdeactivate.8.in | 91 +++++++++++++++++++++++++-------------------------
 1 file changed, 46 insertions(+), 45 deletions(-)

diff --git a/man/blkdeactivate.8.in b/man/blkdeactivate.8.in
index bfd0204..69935b5 100644
--- a/man/blkdeactivate.8.in
+++ b/man/blkdeactivate.8.in
@@ -2,58 +2,60 @@
 .SH "NAME"
 blkdeactivate \(em utility to deactivate block devices
 .SH SYNOPSIS
-.B blkdeactivate
-.RI [ options ]
-.RI [ device... ]
-.sp
+.SY blkdeactivate
+.OP \-d dm_options
+.OP \-e
+.OP \-h
+.OP \-l lvm_options
+.OP \-u
+.OP \-v
+.RI [ device ]
+.YS
 .SH DESCRIPTION
-blkdeactivate utility deactivates block devices. If a device
-is mounted, the utility can unmount it automatically before
-trying to deactivate. The utility currently supports
-\fIdevice-mapper\fP devices, including \fILVM\fP volumes.
-LVM volumes are handled directly using the \fIlvm\fP command.
-Other device-mapper based devices are handled using the
-\fIdmsetup\fP command.
+.B Blkdeactivate
+utility deactivates block devices. If a device is mounted, the utility can
+unmount it automatically before trying to deactivate. The utility currently
+supports device-mapper devices, including LVM volumes. LVM volumes are handled
+directly using the \fBlvm\fP(8) command. Other device-mapper based devices are
+handled using the \fBdmsetup\fP(8) command.
 .SH OPTIONS
 .TP
+.BR "\-d \fIdm_options\fP", " \-\-dmoption \fIdm_options\fP"
+Comma separated list of device-mapper specific options. \fBDmsetup\fP(8)
+options accepted are :
+.RS
+.IP \fIretry\fP
+Retry removal several times in case of failure;
+.IP \fIforce\fP
+Force device removal.
+.RE
+.TP
 .BR \-e ", " \-\-errors
-Show errors reported from tools called by blkdeactivate.
-Without this option, any error messages from these external tools
-are suppressed and the blkdeactivate itself provides only a summary
-message about device being skipped or not.
+Show errors reported from tools called by \fBblkdeactivate\fP. Without this
+option, any error messages from these external tools are suppressed and the
+\fBblkdeactivate\fP itself provides only a summary message about device being
+skipped or not.
 .TP
 .BR \-h ", " \-\-help
 Display the help text.
 .TP
+.BR "\-l \fIlvm_options\fP", " \-\-lvmoption \fIlvm_options\fP"
+Comma separated list of LVM specific options.
+.RS
+.IP \fIretry\fP
+Retry removal several times in case of failure;
+.IP \fIwholevg\fP
+Deactivate the whole LVM Volume Group when processing a Logical Volume.
+Deactivating Volume Group as a whole takes less time than deactivating each
+Logical Volume separately.
+.RE
+.TP
 .BR \-u ", " \-\-umount
-Unmount a mounted device before trying to deactivate it.
-Without this option used, a device that is mounted is not deactivated.
+Unmount a mounted device before trying to deactivate it. Without this option
+used, a device that is mounted is not deactivated.
 .TP
 .BR \-v ", " \-\-verbose
 Run in verbose mode.
-.TP
-.BR \-d ", " \-\-dmoption " " \fIdm_options
-Comma separated list of device-mapper specific options.
-.TP
-.BR \-l ", " \-\-lvmoption " " \fIlvm_options
-Comma separated list of LVM specific options.
-.SH DM_OPTIONS
-.TP
-.B retry
-Retry removal several times in case of failure.
-.TP
-.B force
-Force device removal. See \fBdmsetup\fP(8) for more information.
-.SH LVM_OPTIONS
-.TP
-.B retry
-Retry removal several times in case of failure.
-.TP
-.B wholevg
-Deactivate the whole LVM Volume Group when processing a Logical Volume.
-Deactivating Volume Group as a whole takes less time than deactivating
-each Logical Volume separately.
-
 .SH EXAMPLES
 .sp
 Deactivate all supported block devices found in the system. If a device
@@ -81,9 +83,8 @@ Deactivate all supported block devices found in the system. Retry deactivation
 of device-mapper devices in case the deactivation fails and force removal.
 .sp
 .B blkdeactivate \-d force,retry
-
 .SH SEE ALSO
-.BR lsblk (8)
-.BR umount (8)
-.BR dmsetup (8)
-.BR lvm (8)
+.BR dmsetup (8),
+.BR lsblk (8),
+.BR lvm (8),
+.BR umount (8).
-- 
2.1.3

Improvement of manpages clvmd.8 and blkdeactivate.8

[Zdenek Kabelac]

Dne 15.11.2014 v 17:46 saulery at free.fr napsal(a):
>
> Hello,
>
> Here is a much improved version of blkdeactivate.8 clvmd.8 and manpages. I can
> update others in the same way if you're interested.
>

This patch set has been only partially accepted.

We cannot use  .OP groff macro since it's not compatible with older systems
(i.e. RHEL5) which do not have them build in and so far we support very wide
set of system to compile on.

Also we generally document long option with adding  '-x' short cut on the same 
line - which is likely not fully compliant but yet well readable.

Also I'm not convinced removing space in option list leads to better man page 
formatting.

So few changes are different from your patches.

Please supply groff error list (ideally with the way how to reproduce)
so we could easily see if there is a way to be more consistent yet
we could avoid rewriting everything.

We would already have 'generated' man pages - yet noone stepped into this 
field yet.

Idea is - to use 'single' place for options and doc for option and generate 
man pages and command line options from it (since current way of hand writing 
is usually not in the closest touch with source code).

Zdenek

Improvement of manpages clvmd.8 and blkdeactivate.8

[Stéphane Aulery]

Hello Zdenek,

Le mercredi 19 novembre 2014 ? 01:28:46, Zdenek Kabelac a ?crit :
> Dne 15.11.2014 v 17:46 saulery at free.fr napsal(a):
> >
> >Here is a much improved version of blkdeactivate.8 clvmd.8 and manpages. I can
> >update others in the same way if you're interested.
> >
> 
> This patch set has been only partially accepted.
> 
> We cannot use  .OP groff macro since it's not compatible with older systems
> (i.e. RHEL5) which do not have them build in and so far we support very wide
> set of system to compile on.
> 
> Also we generally document long option with adding  '-x' short cut on the
> same line - which is likely not fully compliant but yet well readable.

Ok. I was not aware of this limitation. Can you use the BSD mdoc format?

> 
> Also I'm not convinced removing space in option list leads to better man
> page formatting.

On this point, I do not look for better formatting but explain the options
usage.According to a case, some have a space, others do not. I thought the
text using /daemons/clvmd/clvmd.c (bx example -E).

There is more than one program (I don't for lvm in particular) that mixes
options, with and without space. It's inconsistent and crazy.

> So few changes are different from your patches.

And I'm not upset. It's good for me.

> Please supply groff error list (ideally with the way how to reproduce)
> so we could easily see if there is a way to be more consistent yet
> we could avoid rewriting everything.

You can use this for syntax errors:

$GROFF_ENCODING=utf8 groff -b -ww -z -mandoc mymanpage.8

I don't know any check program for man macros.

For a complete list, see section STYLE GUIDE of "man-pages" manpage.

 * Program name must be in bold ;
 * Citation of options in text must be in bold ;
 * Citation of option arguments in text must be in italic ;
 * Any reference to another man page should be written with the name in bold ;
 * Entries of SEE ALSO section must be sorted by section number, then by name ;
 * Cite short ant long option integrally ;
 * Sort options to accelerate research ;
 * Be clear (and consistent if possible) with the syntax options ;
 * [...]

Then we can argue. I find that these recommendations are generally good.
The most important is the general consistency across all pages and
fidelity to the behavior of programs, of course.

> We would already have 'generated' man pages - yet noone stepped into this
> field yet.
> 
> Idea is - to use 'single' place for options and doc for option and generate
> man pages and command line options from it (since current way of hand
> writing is usually not in the closest touch with source code).

This is a big deal. I do not even know if it's a good idea in the end
because even directly in the code, all the explanations of an option can
not be found in one place. At best it is possible to generate the
overall page structure, but it will still change the rest by hand. It
adds a lot of complexity for not guarantee results.

Another solution is literate programming. I doubt you want to rewrite
all :-))

Alternatively, you can generate pages from a lightweight markup language
for easy maintenance.

Regards,

-- 
St?phane Aulery

Improvement of manpages clvmd.8 and blkdeactivate.8

[Zdenek Kabelac]

Dne 19.11.2014 v 02:43 St?phane Aulery napsal(a):
> Hello Zdenek,
>
> Le mercredi 19 novembre 2014 ? 01:28:46, Zdenek Kabelac a ?crit :
>> Dne 15.11.2014 v 17:46 saulery at free.fr napsal(a):
>>>
>>> Here is a much improved version of blkdeactivate.8 clvmd.8 and manpages. I can
>>> update others in the same way if you're interested.
>>>
>>
>> This patch set has been only partially accepted.
>>
>> We cannot use  .OP groff macro since it's not compatible with older systems
>> (i.e. RHEL5) which do not have them build in and so far we support very wide
>> set of system to compile on.
>>
>> Also we generally document long option with adding  '-x' short cut on the
>> same line - which is likely not fully compliant but yet well readable.
>
> Ok. I was not aware of this limitation. Can you use the BSD mdoc format?

Maybe there is a way how to provide 'embeded' macro definition with lvm2 code 
base - so if they are not available in the system - built-in definition from 
lvm2 would be user ? - something like .m4 macros fro configure  - though I'm
surely not man-page/groff expert here.

>
> You can use this for syntax errors:
>
> $GROFF_ENCODING=utf8 groff -b -ww -z -mandoc mymanpage.8

I'll check

>
> I don't know any check program for man macros.
>
> For a complete list, see section STYLE GUIDE of "man-pages" manpage.
>
>   * Program name must be in bold ;
>   * Citation of options in text must be in bold ;
>   * Citation of option arguments in text must be in italic ;
>   * Any reference to another man page should be written with the name in bold ;
>   * Entries of SEE ALSO section must be sorted by section number, then by name ;
>   * Cite short ant long option integrally ;
>   * Sort options to accelerate research ;
>   * Be clear (and consistent if possible) with the syntax options ;
>   * [...]

All those are mostly known and agreed, but there are no hands to change them 
all and moreover even fix them.

> Then we can argue. I find that these recommendations are generally good.
> The most important is the general consistency across all pages and
> fidelity to the behavior of programs, of course.
>
>> We would already have 'generated' man pages - yet noone stepped into this
>> field yet.
>>
>> Idea is - to use 'single' place for options and doc for option and generate
>> man pages and command line options from it (since current way of hand
>> writing is usually not in the closest touch with source code).
>
> This is a big deal. I do not even know if it's a good idea in the end
> because even directly in the code, all the explanations of an option can
> not be found in one place. At best it is possible to generate the
> overall page structure, but it will still change the rest by hand. It
> adds a lot of complexity for not guarantee results.
>
> Another solution is literate programming. I doubt you want to rewrite
> all :-))

The problem here is - we try to keep 'meaning' of option consistent across 
commands, but it's often forgotten in which commands the individual option
are used - so if the description for an option is fixed in one place, it then 
still appear in some broken form in other command.  Also users tend to be 
often confused where 'common' options are only described in 'man lvm(8)' and 
they are missing in the command itself.

So having a single place for option description would make things much easier 
to maintain.

Maybe there is already some solution for this used in some other projects ?

Regards

Zdenek