add one-line descriptions to each program usage()

add one-line descriptions to each program usage()

[Karel Zak]

See commit:

https://github.com/stevenhoneyman/util-linux/commit/d5b828e418102b354025bbf7f91b2dcdfc1f4e66

the idea is to add one-line descriptions to each program usage().

Comments?

 IMHO it's not so bad idea, the description will be translated, and
 --help output more informative. Note that for example coreutils use it
 too.

 Anyway, the patch is not ready. I don't like the command name in the
 description -- it's redundant.

 Maybe it would be better to move the description above Options
 section. Something like

---
 Usage:
   fdisk [options] <disk>      change partition table
   fdisk [options] -l [<disk>] list partition table(s)

 Manipulate and list disk partition table.       <---!

 Options:
    -b, --sector-size <size>      physical and logical sector size
    ...
---

    Karel

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

Re: add one-line descriptions to each program usage()

[Benno Schulenberg]

On Wed, Aug 6, 2014, at 15:27, Karel Zak wrote:
> https://github.com/stevenhoneyman/util-linux/commit/d5b828e418102b354025bbf7f91b2dcdfc1f4e66
> 
> the idea is to add one-line descriptions to each program usage().

Yes, docstrings are a good idea.

>  Anyway, the patch is not ready. I don't like the command name in the
>  description -- it's redundant.

Furthermore, each docstring should be a full, grammatical sentence, not
the telegram style used in the NAME section of man pages.  And each of
them should start with a capital and end with a period.  And, if needed,
it may also cover two lines.

>  Maybe it would be better to move the description above Options
>  section.

Yes, that is a better place for them.  That is where coreutils puts them,
too.

As an example, the docstring of the following three commands should
probably be the same: "Display or manipulate a disk partition table.\n":

> fputs(_("fdisk - manipulate disk partition table\n"), out);
> fputs(_("sfdisk - partition table manipulator for Linux\n"), out);
> fputs(_("cfdisk - display or manipulate a disk partition table\n"), out);

Or if not, then the docstrings should make clear how these three differ.

By the way, the scripted grabbing of the first line of the man page as
a docstring has gone wrong for the swapoff command.

Benno

-- 
http://www.fastmail.fm - Choose from over 50 domains or use your own

Re: add one-line descriptions to each program usage()

[Karel Zak]

On Wed, Aug 06, 2014 at 06:04:43PM +0200, Benno Schulenberg wrote:
> On Wed, Aug 6, 2014, at 15:27, Karel Zak wrote:
> > https://github.com/stevenhoneyman/util-linux/commit/d5b828e418102b354025bbf7f91b2dcdfc1f4e66
> > 
> > the idea is to add one-line descriptions to each program usage().
> 
> Yes, docstrings are a good idea.
> 
> >  Anyway, the patch is not ready. I don't like the command name in the
> >  description -- it's redundant.
> 
> Furthermore, each docstring should be a full, grammatical sentence, not
> the telegram style used in the NAME section of man pages.  And each of
> them should start with a capital and end with a period.  And, if needed,
> it may also cover two lines.
> 
> >  Maybe it would be better to move the description above Options
> >  section.
> 
> Yes, that is a better place for them.  That is where coreutils puts them,
> too.
> 
> As an example, the docstring of the following three commands should
> probably be the same: "Display or manipulate a disk partition table.\n":
> 
> > fputs(_("fdisk - manipulate disk partition table\n"), out);
> > fputs(_("sfdisk - partition table manipulator for Linux\n"), out);
> > fputs(_("cfdisk - display or manipulate a disk partition table\n"), out);
> 
> Or if not, then the docstrings should make clear how these three differ.
> 
> By the way, the scripted grabbing of the first line of the man page as
> a docstring has gone wrong for the swapoff command.

 Benno, do you want to work on this task? It seems that the original
 author is no motivated enough to refresh the patch :-) I think it's
 good idea to provide more information in --help output.

    Karel

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

Re: add one-line descriptions to each program usage()

[Benno Schulenberg]

On Wed, Oct 1, 2014, at 10:06, Karel Zak wrote:
> On Wed, Aug 06, 2014 at 06:04:43PM +0200, Benno Schulenberg wrote:
> > On Wed, Aug 6, 2014, at 15:27, Karel Zak wrote:
> > > https://github.com/stevenhoneyman/util-linux/commit/d5b828e418102b354025bbf7f91b2dcdfc1f4e66
> > > 
> > > the idea is to add one-line descriptions to each program usage().
> > 
> > Yes, docstrings are a good idea.  [...]
> 
>  Benno, do you want to work on this task?

Okay, will do.  It may take, however, a week or two before I find
enough time to do this.

Benno

-- 
http://www.fastmail.fm - Access all of your messages and folders
                          wherever you are