s390-tools/s390-tools-sles15-lsluns-fix-flawed-formatting-of-man-page.patch

Subject: [PATCH] [BZ 161888] lsluns: fix flawed formatting of man page
From: Jens Remus <jremus@linux.vnet.ibm.com>

Description:  lsluns: Fix filter handling and documentation enhancements.
Symptom:      lsluns lists all LUNs discovered in the FC SAN despite user
              given filter(s) that do not match anything:
                # lsluns -c 0.0.5080
                    No valid combination found for adapter '0.0.5080'. Removing
                    from resource list.
                No valid parameters left, using all available resources in
                system.
                Scanning for LUNs on adapter 0.0.5090
                ...

              lsluns prints the message "No valid combination found for
              {adapter|port} '...'. Removing from resource list." for every
              adapter and port filter that does not contribute to the final
              filtered results.

              The formatting of the lsluns (8) man page is flawed.

              lsluns is used in unexpected or even unsupported ways.
Problem:      Scanning can be resource consumptive. So if a user already wants
              to filter, possibly to reduce resource consumption, he does not
              want to happen to scan everything and thus consume the worst case
              of resources.

              The message "No valid combination found for {adapter|port} '...'.
              Removing from resource list." is potentially confusing. It is
              unclear which combination is being referred to, especially if
              only one single adapter or port filter was specified. There is
              also no differentiation whether the denoted adapter or port
              exists for its own or not. It just does not exist in the final
              filtered results.

              The formatting of the lsluns (8) man page is flawed.

              The lsluns usage text and lsluns (8) man page lack the
              information on the intended use cases, requirements, and
              restrictions.
Solution:     Print a message and exit when all filters match nothing.

              Do not print confusing messages when a filter matches nothing.

              Fix man page formatting.

              Enhance usage text and man page. Clarify discovery use case,
              relation to NPIV and to zfcp auto LUN scan. Point out
              IBM Storwize configuration requirements. Document restriction to
              zfcp-only systems.
Reproduction: Use lsluns and specify adapter bus-ID and/or target port WWPN
              filter(s) that do not match anything. Either specify inexistent
              bus-IDs and/or WWPNs or invalid filter arguments.
Upstream-ID:  d81c4234295f481559a74fb5ad5f498692ff5738
Problem-ID:   161888

Upstream-Description:

              lsluns: fix flawed formatting of man page

              The formatting in the SYNOPSIS, OPTIONS, and EXAMPLES sections was flawed
              in the lsluns(8) man page:

              * The comma between short and long options were erroneously formatted in
                bold, which would indicate to be typed exactly as shown. [see man(1)]

              * The option parameters (e.g. adapter and port) were erroneously formatted
                in bold instead of italic text (usually displayed as underlined on the
                console), which would again indicate to be typed exactly as shown instead
                of to be replaced with the appropriate argument. [see man(1)]

              * Ellipses were missing after the the options that may be specified multiple
                times (e.g. adapter and port). [see man(1)]

              * Dashes in options in the SYNOPSIS and OPTIONS section needed to be
                escaped. [see man-pages(7)]

              * User input in example shell sessions should have been formatted in bold.
                [see man-pages(7)]

              Correct formatting based on man(7) and man-pages(7) man pages as reference.
              Add proper spacing between options and their surrounding square brackets and
              between the three periods of ellipses.

              Signed-off-by: Jens Remus <jremus@linux.vnet.ibm.com>
              Reviewed-by: Steffen Maier <maier@linux.vnet.ibm.com>
              Reviewed-by: Benjamin Block <bblock@linux.vnet.ibm.com>
              Signed-off-by: Michael Holzheu <holzheu@linux.vnet.ibm.com>


Signed-off-by: Jens Remus <jremus@linux.vnet.ibm.com>
---
 zconf/lsluns.8 |   42 +++++++++++++++++++++++-------------------
 1 file changed, 23 insertions(+), 19 deletions(-)

--- a/zconf/lsluns.8
+++ b/zconf/lsluns.8
@@ -8,12 +8,12 @@ lsluns \- list available LUNs
 
 .SH SYNOPSIS
 .B lsluns
-.RB [ \-h]
-.RB [ \-v]
-.RB [ \-c
-.IR adapter id:0.0.XXXX ]
+.RB [\| \-h \|]
+.RB [\| \-v \|]
+.RB [\| \-c
+.IR adapter\ id:0.0.XXXX \|]\ .\|.\|.
 .RB [ \-p
-.IR port number:0xXXXXXXXXXXXXXXXX ]
+.IR port\ number:0xXXXXXXXXXXXXXXXX \|]\ .\|.\|.
 
 .SH DESCRIPTION
 .PP
@@ -25,36 +25,40 @@ limited by specifying an adapter or a po
 
 .SH OPTIONS
 .TP
-.B -h, --help
+.BR \-h ", " \-\-help
 Print help message and exit.
 .TP
-.B -v, --version
+.BR \-v ", " \-\-version
 Display version info and exit.
 .TP
-.B -c, --ccw
+.BI \-c\  adapter \fR,\ \fB\-\-ccw= adapter
 Shows LUNs for a specific adapter.
 .TP
-.B -p, --port
+.BI \-p\  port \fR,\ \fB\-\-port= port
 Shows LUNs for a specific port.
 .TP
-.B -a, --active
+.BR \-a ", " \-\-active
 Shows all activated LUNs. In addition information is provided
 whether the LUN is encrypted or not. This is indicated with a bracketed X 
 right after the LUN number.
 
 .SH EXAMPLES
-.PP
-.IP "lsluns"
+.TP
+.B "lsluns"
 .RS
 Shows all available LUNs.
 .RE
-.IP "lsluns -c 0.0.3922"
-Shows all LUNs found on adapter 0.0.3922.
-.IP "lsluns -p 0x5005123456789000"
-Shows all LUNs for port 0x5005123456789000.
-.IP "lsluns -c 0.0.3922 -p 0x5005123456789000"
-Shows all LUNs for adapter 0.0.3922 and port 0x5005123456789000.
-.IP "lsluns -a "
+.TP
+.BI "lsluns \-c " 0.0.3922
+Shows all LUNs found on adapter \fI0.0.3922\fR.
+.TP
+.BI "lsluns \-p " 0x5005123456789000
+Shows all LUNs for port \fI0x5005123456789000\fR.
+.TP
+.BI "lsluns \-c " 0.0.3922 " \-p " 0x5005123456789000
+Shows all LUNs for adapter \fI0.0.3922\fR and port \fI0x5005123456789000\fR.
+.TP
+.B "lsluns -a"
 adapter = 0.0.3c02
         port = 0x500507630300c562
                 lun = 0x401040a200000000(X)     /dev/sg0        Disk    IBM:2107900