Improvement suggestion for mkfs.8 manpage

Improvement suggestion for mkfs.8 manpage

[Johannes Unglert]

[-- Attachment #1: Type: text/plain, Size: 567 bytes --]

Hello,

i stumbled upon a minor spelling error in the mkfs.8 manpage.
It´s an capitalization error for the verbose option.

Please see attached diff for more information.

How should i handle this? What´s the desired procedure?
Do you want me to create a pull-request?


with best regards

Johannes Unglert
-- 
Johannes Unglert
Auszubildender Fachinformatik - AE
Tel.: +49 1512 2088159
Mail: unglert@b1-systems.de

B1 Systems GmbH
Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt, HRB 3537

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: mkfs.8.patch --]
[-- Type: text/x-patch; name="mkfs.8.patch", Size: 767 bytes --]

*** util-linux/disk-utils/mkfs.8	2019-02-06 16:16:12.585415680 +0100
--- util-linux/disk-utils/mkfs.8.new	2019-02-06 16:16:25.693415630 +0100
***************
*** 43,49 ****
  .I fs-options
  Filesystem-specific options to be passed to the real filesystem builder.
  .TP
! .BR \-V , " \-\-verbose"
  Produce verbose output, including all filesystem-specific commands
  that are executed.
  Specifying this option more than once inhibits execution of any
--- 43,49 ----
  .I fs-options
  Filesystem-specific options to be passed to the real filesystem builder.
  .TP
! .BR \-v , " \-\-verbose"
  Produce verbose output, including all filesystem-specific commands
  that are executed.
  Specifying this option more than once inhibits execution of any

Re: Improvement suggestion for mkfs.8 manpage

[Theodore Y. Ts'o]

On Wed, Feb 06, 2019 at 04:43:14PM +0100, Johannes Unglert wrote:
> Hello,
> 
> i stumbled upon a minor spelling error in the mkfs.8 manpage.
> It´s an capitalization error for the verbose option.

The existing man page is correct, as near as I can determine; the -V
is the verbose option to the mkfs wrapper program.  For many file
system mkfs.FSTYP back ends -v is an option that will ask the
mkfs.FSTYP command to be verbose, but that's a different thing.

					- Ted

Re: Improvement suggestion for mkfs.8 manpage

[Johannes Unglert]

Hi,

thank you for the quick answer.

>> i stumbled upon a minor spelling error in the mkfs.8 manpage.
>> It´s an capitalization error for the verbose option.
>
> The existing man page is correct, as near as I can determine; the -V
> is the verbose option to the mkfs wrapper program.  For many file
> system mkfs.FSTYP back ends -v is an option that will ask the
> mkfs.FSTYP command to be verbose, but that's a different thing.


I think I described the error the wrong way.
In the mkfs manpage there are two -V options:
One for 'verbose' and one for 'version'.

The two -V options are both written with a capital letter.
It is ambiguous and I think this should not be intentional.


Please correct me if I'm missing anything here.


With best regards

Johannes Unglert

-- 
Johannes Unglert
Auszubildender Fachinformatik - AE
Tel.: +49 1512 2088159
Mail: unglert@b1-systems.de

B1 Systems GmbH
Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt, HRB 3537

Re: Improvement suggestion for mkfs.8 manpage

[Theodore Y. Ts'o]

On Fri, Feb 08, 2019 at 10:47:47AM +0100, Johannes Unglert wrote:
> 
> I think I described the error the wrong way.
> In the mkfs manpage there are two -V options:
> One for 'verbose' and one for 'version'.
> 
> The two -V options are both written with a capital letter.
> It is ambiguous and I think this should not be intentional.
> 
> Please correct me if I'm missing anything here.

I noticed this, and it's weird, but what's there is technically
correct in that it accurately described how mkfs works:

       -V, --verbose
              Produce  verbose  output, including all filesystem-specific com‐
              mands that are executed.  Specifying this option more than  once
              inhibits execution of any filesystem-specific commands.  This is
              really only useful for testing.

       -V, --version
              Display version information and exit.  (Option -V  will  display
              version  information  only when it is the only parameter, other‐
              wise it will work as --verbose.)

That is, "mkfs -V" == "mkfs --version".

However "mkfs --verbose -- -Fq -t ext4 /tmp/foo.img 4M" is the same as:
"mkfs -V -- -Fq -t ext4 /tmp/foo.img 4M"

I don't think most people notice this because most people they tend
not to use the mkfs wrapper in this mode.  In general, they will use
"mkfs.ext4" instead of "mkfs -t ext4".  Which is good because it's
actually a bit buggy:

% mkfs -V -t ext4 -Fq /tmp/foo.img 4M
mkfs from util-linux 2.33.1
mkfs.ext4 ext4 -Fq /tmp/foo.img 4M 
mkfs.ext4: invalid blocks '/tmp/foo.img' on device 'ext4'

In general, I generally recommend that people use /sbin/mkfs.ext4 or
/sbin/mke2fs -t ext4, because the mkfs wrapper doesn't add much value,
and it gets confusing which options are parameters are grabbed by
mkfs, and which will get passed to the back-end mkfs program.

Cheers,

					- Ted

Re: Improvement suggestion for mkfs.8 manpage

[Karel Zak]

On Fri, Feb 08, 2019 at 10:20:02AM -0500, Theodore Y. Ts'o wrote:
> In general, I generally recommend that people use /sbin/mkfs.ext4 or
> /sbin/mke2fs -t ext4, because the mkfs wrapper doesn't add much value,
> and it gets confusing which options are parameters are grabbed by
> mkfs, and which will get passed to the back-end mkfs program.

Yes, the first sentence in the DESCRIPTION section:

  This mkfs frontend is deprecated in favour of filesystem specific mkfs.<type> utils.


Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com