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@xxxxxxxxxx> http://karelzak.blogspot.com -- To unsubscribe from this list: send the line "unsubscribe util-linux" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
