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 -- 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
