Re: Unify the --help and --version descriptions in man pages?

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hello Karel,

Am Mo., 31. Jan. 2022 um 10:35 Uhr schrieb Karel Zak <kzak@xxxxxxxxxx>:
>
> On Sat, Jan 29, 2022 at 12:57:12PM +0100, Mario Blättermann wrote:
> > I've just noticed the commit »docs: add man-common/in-bytes.adoc«.
> > What about to unify the descriptions of the --help and the --version
> > options in the man pages in a similar manner? Besides to simplify the
> > maíntenance, it would also shrink the .po file of the man pages a bit.
>
> Arbitrary unification and consolidation is wanted, go ahead ;-)
>
> > --- blockdev.8.adoc     2021-11-26 17:40:06.931013901 +0100
> > +++ blockdev.8.adoc    2022-01-29 12:47:43.087144014 +0100
> > @@ -40,10 +40,10 @@
> > Print a report for the specified device. It is possible to give multiple device
> > s. If none is given, all devices which appear in _/proc/partitions_ are shown. N
> > ote that the partition StartSec is in 512-byte sectors.
> >
> > *-h*, *--help*::
> > -Display help text and exit.
> > +include::man-common/help-description.adoc[]
> >
> > *-V*, *--version*::
> > -Print version and exit.
> > +include::man-common/version-description.adoc[]
>
> Do we need to separate help & version? Maybe we can use
>
>   include::man-common/help-and-version.adoc[]
>
> where will be everything.
>
>       *-h*, *--help*
>               Display help text and exit.
>
>       *-V*, *--version*
>               Display version information and exit.
>
> We use the same in usage() function (--help output) where both
> items are printed together by USAGE_HELP_OPTIONS macro. (see 'git grep
> USAGE_HELP_OPTIONS')
>
> IMHO --help and --version is so generic that we do not need to keep it
> sorted in man pages. I guess it's OK to keep it at the end of the list
> of options like we use in usage().


OK, this is possible for --help without any other changes; all our
tools have the same options (*-h*, *--help*). But for --version, the
single-letter option differs. While most of the tools have *-V*,
*--version*, it is *-v*, *--version* for the following ones:

sfdisk.8.adoc
chsh.1.adoc
chfn.1.adoc

For sfdisk, -V has a different meaning, and for chsh and chfn the
option -V is unknown (invalid). So we could change chsh and chfn to
accept -V (and maybe drop -v in turn), and we leave the --help and
--version part of sfdisk.8.adoc untouched.

 >
> > BTW, are there any plans for the next release 2.38? I'm planning to
>
> The last remaining patch is x-fstrim from Stanislav and than I'll
> release v2.38-rc1 :-) (so today).
>
> > add direct support for Fedora 36 in manpages-l10n (once it is
> > available from the servers), in addition to Rawhide. If v2.38 will
> > come with Fedora 36, I could adjust the package lists appropriately,
> > to avoid file conflicts.
>
> F36 beta freeze is 2022-03-15, it seems we have enough time.
>
So I assume you plan to release the final v2.38 until this Fedora Beta
gets rolled out, including the translated man pages?

Best Regards,
Mario




[Index of Archives]     [Netdev]     [Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux