[PATCH 0/4] pull request

[PATCH 0/4] pull request

[J William Piggott]

* Rudi didn't like cluttering boilerplate.c with seldom used USAGE_*
  constants and I don't disagree with that point. I do think they should
  be in the file for new contributor discovery purposes. As a compromise
  I added the missing ones as a comment.

* the newly added USAGE_COLUMNS could be used in disk-utils/fdisk-list.c:432
  if Karel wants to drop the ' (for -o)'. I did not change it.

* I couldn't test the blkzone change to USAGE_COMMANDS, but I expect it to
  be okay.
   configure: WARNING: linux/blkzoned.h header not found; not building blkzone


The following changes since commit 2a14beb4e9c6cdf4466993741d86e45dd57ddef3:

  agetty: fix login name DEL/CTRL^U issue (2017-06-23 14:26:47 +0200)

are available in the git repository at:

  git@github.com:jwpi/util-linux.git 170622

for you to fetch changes up to 7948117da5654311dba59b256d9a017d56877592:

  Docs: move option naming to howto-contribute.txt (2017-06-24 15:22:49 -0400)

----------------------------------------------------------------
J William Piggott (4):
      include/c.h: add USAGE_COMMANDS and USAGE_COLUMNS
      Docs: add a comment for constants to boilerplate.c
      Docs: update howto-usage-function.txt
      Docs: move option naming to howto-contribute.txt

 Documentation/boilerplate.c            |  8 +--
 Documentation/howto-contribute.txt     | 25 +++++++++
 Documentation/howto-usage-function.txt | 97 +++++++++++++---------------------
 disk-utils/sfdisk.c                    |  2 +-
 include/c.h                            |  4 +-
 login-utils/lslogins.c                 |  6 +--
 misc-utils/findmnt.c                   |  3 +-
 sys-utils/blkzone.c                    |  2 +-
 sys-utils/lscpu.c                      |  3 +-
 sys-utils/lsmem.c                      |  5 +-
 sys-utils/wdctl.c                      |  3 +-
 11 files changed, 78 insertions(+), 80 deletions(-)

[PATCH 1/4] include/c.h: add USAGE_COMMANDS and USAGE_COLUMNS

[J William Piggott]

* login-utils/lslogins.c: all uses changed
* misc-utils/findmnt.c: likewise
* sys-utils/blkzone.c: likewise
* disk-utils/sfdisk.c: likewise
* sys-utils/lscpu.c: likewise
* sys-utils/lsmem.c: likewise
* sys-utils/wdctl.c: likewise

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 disk-utils/sfdisk.c    | 2 +-
 include/c.h            | 4 +++-
 login-utils/lslogins.c | 6 ++----
 misc-utils/findmnt.c   | 3 +--
 sys-utils/blkzone.c    | 2 +-
 sys-utils/lscpu.c      | 3 +--
 sys-utils/lsmem.c      | 5 ++---
 sys-utils/wdctl.c      | 3 +--
 8 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/disk-utils/sfdisk.c b/disk-utils/sfdisk.c
index 2ac8cef..2a75190 100644
--- a/disk-utils/sfdisk.c
+++ b/disk-utils/sfdisk.c
@@ -1850,7 +1850,7 @@ static void __attribute__ ((__noreturn__)) usage(FILE *out)
 	fputs(USAGE_SEPARATOR, out);
 	fputs(_("Display or manipulate a disk partition table.\n"), out);
 
-	fputs(_("\nCommands:\n"), out);
+	fputs(USAGE_COMMANDS, out);
 	fputs(_(" -A, --activate <dev> [<part> ...] list or set bootable MBR partitions\n"), out);
 	fputs(_(" -d, --dump <dev>                  dump partition table (usable for later input)\n"), out);
 	fputs(_(" -J, --json <dev>                  dump partition table in JSON format\n"), out);
diff --git a/include/c.h b/include/c.h
index 2bcdcea..f89e065 100644
--- a/include/c.h
+++ b/include/c.h
@@ -313,11 +313,13 @@ static inline int xusleep(useconds_t usec)
 
 /*
  * Constant strings for usage() functions. For more info see
- * Documentation/howto-usage-function.txt and disk-utils/delpart.c
+ * Documentation/{howto-usage-function.txt,boilerplate.c}
  */
 #define USAGE_HEADER     _("\nUsage:\n")
 #define USAGE_OPTIONS    _("\nOptions:\n")
 #define USAGE_FUNCTIONS  _("\nFunctions:\n")
+#define USAGE_COMMANDS   _("\nCommands:\n")
+#define USAGE_COLUMNS    _("\nAvailable columns:\n")
 #define USAGE_SEPARATOR    "\n"
 #define USAGE_HELP       _(" -h, --help     display help information and exit\n")
 #define USAGE_VERSION    _(" -V, --version  display version information and exit\n")
diff --git a/login-utils/lslogins.c b/login-utils/lslogins.c
index ab04c10..9cbf0b3 100644
--- a/login-utils/lslogins.c
+++ b/login-utils/lslogins.c
@@ -1255,11 +1255,9 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
 
-	fprintf(out, _("\nAvailable columns:\n"));
-
+	fputs(USAGE_COLUMNS, out);
 	for (i = 0; i < ARRAY_SIZE(coldescs); i++)
-		fprintf(out, " %14s  %s\n", coldescs[i].name,
-				_(coldescs[i].help));
+		fprintf(out, " %14s  %s\n", coldescs[i].name, _(coldescs[i].help));
 
 	fprintf(out, USAGE_MAN_TAIL("lslogins(1)"));
 
diff --git a/misc-utils/findmnt.c b/misc-utils/findmnt.c
index 93c0e90..7acc60a 100644
--- a/misc-utils/findmnt.c
+++ b/misc-utils/findmnt.c
@@ -1248,8 +1248,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
 
-	fprintf(out, _("\nAvailable columns:\n"));
-
+	fputs(USAGE_COLUMNS, out);
 	for (i = 0; i < ARRAY_SIZE(infos); i++)
 		fprintf(out, " %11s  %s\n", infos[i].name, _(infos[i].help));
 
diff --git a/sys-utils/blkzone.c b/sys-utils/blkzone.c
index 7713ff3..8fd55c0 100644
--- a/sys-utils/blkzone.c
+++ b/sys-utils/blkzone.c
@@ -300,7 +300,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fputs(USAGE_SEPARATOR, out);
 	fputs(_("Run zone command on the given block device.\n"), out);
 
-	fputs(_("\nCommands:\n"), out);
+	fputs(USAGE_COMMANDS, out);
 	for (i = 0; i < ARRAY_SIZE(commands); i++)
 		fprintf(out, " %-11s  %s\n", commands[i].name, _(commands[i].help));
 
diff --git a/sys-utils/lscpu.c b/sys-utils/lscpu.c
index 3b549a7..2871f71 100644
--- a/sys-utils/lscpu.c
+++ b/sys-utils/lscpu.c
@@ -2068,8 +2068,7 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
 
-	fprintf(out, _("\nAvailable columns:\n"));
-
+	fputs(USAGE_COLUMNS, out);
 	for (i = 0; i < ARRAY_SIZE(coldescs); i++)
 		fprintf(out, " %13s  %s\n", coldescs[i].name, _(coldescs[i].help));
 
diff --git a/sys-utils/lsmem.c b/sys-utils/lsmem.c
index 0c8adb8..891be36 100644
--- a/sys-utils/lsmem.c
+++ b/sys-utils/lsmem.c
@@ -388,10 +388,9 @@ static void __attribute__((__noreturn__)) lsmem_usage(FILE *out)
 	fputs(USAGE_HELP, out);
 	fputs(USAGE_VERSION, out);
 
-	fputs(_("\nAvailable columns:\n"), out);
-
+	fputs(USAGE_COLUMNS, out);
 	for (i = 0; i < ARRAY_SIZE(coldescs); i++)
-		fprintf(out, " %10s  %s\n", coldescs[i].name, coldescs[i].help);
+		fprintf(out, " %10s  %s\n", coldescs[i].name, _(coldescs[i].help));
 
 	fprintf(out, USAGE_MAN_TAIL("lsmem(1)"));
 
diff --git a/sys-utils/wdctl.c b/sys-utils/wdctl.c
index e47fc70..1790e89 100644
--- a/sys-utils/wdctl.c
+++ b/sys-utils/wdctl.c
@@ -194,9 +194,8 @@ static void __attribute__ ((__noreturn__)) usage(FILE *out)
 	fputs(USAGE_SEPARATOR, out);
 
 	fprintf(out, _("The default device is %s.\n"), _PATH_WATCHDOG_DEV);
-	fputs(USAGE_SEPARATOR, out);
 
-	fputs(_("Available columns:\n"), out);
+	fputs(USAGE_COLUMNS, out);
 	for (i = 0; i < ARRAY_SIZE(infos); i++)
 		fprintf(out, " %13s  %s\n", infos[i].name, _(infos[i].help));
 

[PATCH 2/4] Docs: add a comment for constants to boilerplate.c

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 Documentation/boilerplate.c | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/Documentation/boilerplate.c b/Documentation/boilerplate.c
index 5b2e59b..b70955d 100644
--- a/Documentation/boilerplate.c
+++ b/Documentation/boilerplate.c
@@ -29,6 +29,11 @@
 #include "closestream.h"
 #include "nls.h"
 
+/*
+ * FIXME: remove this comment.
+ * Other usage() constants that are not demonstrated below:
+ * USAGE_FUNCTIONS USAGE_COMMANDS USAGE_COLUMNS
+ */
 static void __attribute__((__noreturn__)) usage(FILE *out)
 {
 	fputs(USAGE_HEADER, out);
@@ -37,9 +42,6 @@ static void __attribute__((__noreturn__)) usage(FILE *out)
         fputs(USAGE_SEPARATOR, out);
         fputs(_("Short program description.\n"), out);
 
-	fputs(USAGE_FUNCTIONS, out);
-	fputs(_(" -s, --do-something      some specific task\n"), out);
-	fputs(_(" -o, --do-other          some different task\n"), out);
 	fputs(USAGE_OPTIONS, out);
 	fputs(_(" -n, --no-argument       option does not use argument\n"), out);
 	fputs(_("     --optional[=<arg>]  option argument is optional\n"), out);

[PATCH 3/4] Docs: update howto-usage-function.txt

[J William Piggott]

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 Documentation/howto-usage-function.txt | 75 ++++++++++++++++++----------------
 1 file changed, 39 insertions(+), 36 deletions(-)

diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
index 3496b49..1c5c4b8 100644
--- a/Documentation/howto-usage-function.txt
+++ b/Documentation/howto-usage-function.txt
@@ -1,3 +1,9 @@
+
+Example file
+------------
+
+Refer to the ./boilerplate.c example file while reading this howto.
+
 Well-known options
 ------------------
 
@@ -16,19 +22,22 @@ See Legacy options below.
 How a usage text is supposed to look
 ------------------------------------
 
-The usage output begins with an empty line, followed by 'Usage:', and
-then the synopsis on the line after that.  The synopsis and option-
-description lines are all indented by one space (0x40).
+The usage() output format is: Usage section, command description one-liner,
+Options section (see below), special sections like 'Available columns', and
+the last line is either the man page reference or and empty line. The output
+begins with, and each of the above are separated by, one empty line.
+
+The Usage section contains the synopsis line that describes how to compose
+the command. Sometimes you may need multiple synopsis lines (see below).
 
-The synopsis line describes how to compose the command.  Sometimes you
-may need multiple synopsis lines -- this is documented separately in the
-Synopsis section.
+Only the synopsis and option lines are indented. Indent is one space (0x40).
+Option lines do not use line-ending punctuation. Other sentences do.
 
-Notations.  Diamond brackets are used to mark an argument to be filled in.
-Square brackets are used to mark anything that is optional, such as optional
-command arguments, or optional option arguments.  In the later case the '='
-character is needed in front of the option argument, because one has to use
-it.  Three consecutive dots mean the unlimited repetition of the preceding.
+Notations: diamond brackets are used to mark an argument to be filled in;
+square brackets are used to mark anything that is optional, such as optional
+command arguments, or optional option arguments. In the later case the '='
+character is required in between the option and argument with no whitespace;
+three consecutive dots means the unlimited repetition of the preceding.
 
 The short option is always written first, followed by the long option.  They
 are separated with a comma and one space.  Lonely short or long options do
@@ -63,22 +72,21 @@ Options:
 For more details see program(1).
 -- snip
 
-Note that there are usage-function definitions in the 'c.h' include file
-which you must use.  The location of an example file is mentioned at the
-end of this text.
-
 
 Option descriptions
 -------------------
 
+This information also applies to other option-like arguments. That is,
+arguments starting with '-'. Such as: functions, commands, and so forth.
+
 An option description should not exceed the width of 80 characters.  If
 you need a longer description, use multiple lines and indentation.
 
 The description text begins from the point of the longest option plus two
-spaces.  In case adding a new option would necessitate a re-indentation of
-the descriptions, it either has to be done, or the new option should begin
-its description on the next line.  Usually the later is better.  The --help
-and --version options do not follow this rule, since they are defined as
+spaces. If adding a new option would necessitate a re-indentation of the
+descriptions, it either has to be done, or the new option should begin its
+description on the next line.  Usually the later is better. The --help and
+--version options do not follow this rule, since they are defined as
 constants to ease translation work.
 
 An argument is preferably worded appropriately.  For example, if an option
@@ -87,10 +95,6 @@ expects a number as argument, '<num>' is a suitable argument indicator.
 The order of the options has no special meaning, with the exception of
 --help and --version which are expected to be last ones in the list.
 
-The last line of the usage text is either empty, or a message informing
-about the manual page.  For example: 'For more details see example(1).'.
-Between the options and the man-page message there is an empty line.
-
 
 Usage function
 --------------
@@ -99,6 +103,10 @@ The standard usage() function takes either stderr or stdout as an argument.
 The argument will determine whether the program will exit with an error or
 with success.  The usage() function will never return.
 
+Section headers, man page, version, help, and other components of usage()
+have string constants defined in 'include/c.h' which must be used. See the
+example file listed at the top of this document.
+
 In the code all the strings with options have to start at the same position.
 See here what this means:
 
@@ -114,17 +122,17 @@ no less.  For example:
 		"                or how is your klingon?\n"), out);
 
 When existing usage output is changed, and it happens to be one big text,
-split it into chunks the size of one option.  The extra work this will
-entail for translators will pay off later, at the time of the next change,
-when they will not need to search in the long fuzzy text what was changed,
-where, how, and whether it was the only change.
+split it into chunks the size of one option. The extra work this will entail
+for translators will pay off later; the next string change will not force a
+search of the long fuzzy text for what was changed, where, how, and whether
+it was the only change.
 
 
 Synopsis
 --------
 
 You may need to use multiple synopsis lines to show that a command does
-fundamentally different things depending on options and/or arguments.
+fundamentally different things depending on the options and/or arguments.
 For example, ionice either changes the priority of a running command, or
 executes a program with a defined priority.  Therefore it is reasonable
 to have two synopsis lines:
@@ -133,9 +141,9 @@ to have two synopsis lines:
  ionice [options] <command> [<arg> ...]
 
 Note that the synopsis is not meant to be a repetition of the options
-segment.  The fundamental difference in execution is a bit difficult to
-define other than that usually the command author, package maintainer
-or patch submitter will know when it should be done that way.
+section. The fundamental difference in execution is a bit difficult to
+define. The command author, package maintainer or patch submitter will
+usually know when it should be done that way.
 
 
 Legacy options
@@ -152,8 +160,3 @@ additions.  A short list of examples:
   option resulting in a suggestion to try --help due to a getopt failure.
 
 
-Example file
-------------
-
-The file ./boilerplate.c is a minimal example of how to write
-a usage function, set up option parsing, version printing and so on.

[PATCH 4/4] Docs: move option naming to howto-contribute.txt

[J William Piggott]

Creating and naming options is not done when writing usage().
A contributor may not even read howto-usage-function.txt, but
they should read howto-contribute.txt. So move option naming
and change information there.

Signed-off-by: J William Piggott <elseifthen@gmx.com>
---
 Documentation/howto-contribute.txt     | 25 +++++++++++++++++++++++++
 Documentation/howto-usage-function.txt | 28 ----------------------------
 2 files changed, 25 insertions(+), 28 deletions(-)

diff --git a/Documentation/howto-contribute.txt b/Documentation/howto-contribute.txt
index 245f9ab..e63d390 100644
--- a/Documentation/howto-contribute.txt
+++ b/Documentation/howto-contribute.txt
@@ -3,6 +3,7 @@ CONTENTS
  Patching Process
  Email Format
  Coding Style
+ Options
  Various Notes
  Standards Compliance
 
@@ -155,6 +156,30 @@ Coding Style
 	  multiple lines. In case the shorthand does not look good on one line
 	  use the normal "if () else" syntax.
 
+Options
+
+	* The rule of thumb for options is that once they exist, you may not
+	  change them, nor change how they work, nor remove them.
+
+	* The following options are well-known, and should not be used for any
+	  other purpose:
+
+		-h, --help     display usage and exit
+		-V, --version  display version and exit
+
+	* Some commands use peculiar options and arguments. These will continue
+	  to be supported, but anything like them will not be accepted as new
+	  additions. A short list of examples:
+
+		Characters other than '-' to start an option. See '+' in 'more'.
+
+		Using a number as an option. See '-<number>' in 'more'.
+
+		Long options that start with a single '-'. See 'setterm'.
+
+		'-?' is not a synonym for '--help', but is an unknown option
+		resulting in a suggestion to try --help due to a getopt failure.
+
 Various Notes
 
 	* util-linux does not use kernel headers for file system super
diff --git a/Documentation/howto-usage-function.txt b/Documentation/howto-usage-function.txt
index 1c5c4b8..a666d44 100644
--- a/Documentation/howto-usage-function.txt
+++ b/Documentation/howto-usage-function.txt
@@ -4,20 +4,6 @@ Example file
 
 Refer to the ./boilerplate.c example file while reading this howto.
 
-Well-known options
-------------------
-
-The following options are well-known, and should not be used for any
-other purpose:
-
- -h, --help     display usage and exit
- -V, --version  display version and exit
-
-The rule of thumb with other options is that once they exist, you may
-not change them, nor change how they work, nor remove them.
-
-See Legacy options below.
-
 
 How a usage text is supposed to look
 ------------------------------------
@@ -146,17 +132,3 @@ define. The command author, package maintainer or patch submitter will
 usually know when it should be done that way.
 
 
-Legacy options
---------------
-
-Some commands use peculiar options and arguments.  These will continue
-to be supported, but anything like them will not be accepted as new
-additions.  A short list of examples:
-
-- Characters other than '-' to start an option.  See '+' in 'more'.
-- Using a number as an option.  See '-<number>' in 'more'.
-- Long options that start with a single '-'.  See 'setterm'.
-- '-?' is not expected to be a synonym of '--help', but is an unknown
-  option resulting in a suggestion to try --help due to a getopt failure.
-
-

Re: [PATCH 0/4] pull request

[Karel Zak]

On Sun, Jun 25, 2017 at 05:45:56PM -0400, J William Piggott wrote:
> 
> * Rudi didn't like cluttering boilerplate.c with seldom used USAGE_*
>   constants and I don't disagree with that point. I do think they should
>   be in the file for new contributor discovery purposes. As a compromise
>   I added the missing ones as a comment.
> 
> * the newly added USAGE_COLUMNS could be used in disk-utils/fdisk-list.c:432
>   if Karel wants to drop the ' (for -o)'. I did not change it.

I think USAGE_COLUMNS should be good enough everywhere and the
additional notes (like ' (for -o)') are unnecessary.

Maybe we can change the text to "Available output columns:" to make it
more specific for readers.

    Karel


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

Re: [PATCH 0/4] pull request

[Karel Zak]

On Mon, Jun 26, 2017 at 10:27:44AM +0200, Karel Zak wrote:
> On Sun, Jun 25, 2017 at 05:45:56PM -0400, J William Piggott wrote:
> > 
> > * Rudi didn't like cluttering boilerplate.c with seldom used USAGE_*
> >   constants and I don't disagree with that point. I do think they should
> >   be in the file for new contributor discovery purposes. As a compromise
> >   I added the missing ones as a comment.
> > 
> > * the newly added USAGE_COLUMNS could be used in disk-utils/fdisk-list.c:432
> >   if Karel wants to drop the ' (for -o)'. I did not change it.
> 
> I think USAGE_COLUMNS should be good enough everywhere and the
> additional notes (like ' (for -o)') are unnecessary.
> 
> Maybe we can change the text to "Available output columns:" to make it
> more specific for readers.

 Implemented & pull request merged. Thanks.

    Karel

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

Re: [PATCH 0/4] pull request

[J William Piggott]

On 06/26/2017 04:27 AM, Karel Zak wrote:
> On Sun, Jun 25, 2017 at 05:45:56PM -0400, J William Piggott wrote:
>>
>> * Rudi didn't like cluttering boilerplate.c with seldom used USAGE_*
>>   constants and I don't disagree with that point. I do think they should
>>   be in the file for new contributor discovery purposes. As a compromise
>>   I added the missing ones as a comment.
>>
>> * the newly added USAGE_COLUMNS could be used in disk-utils/fdisk-list.c:432
>>   if Karel wants to drop the ' (for -o)'. I did not change it.
> 
> I think USAGE_COLUMNS should be good enough everywhere and the
> additional notes (like ' (for -o)') are unnecessary.
> 
> Maybe we can change the text to "Available output columns:" to make it
> more specific for readers.

Since we cannot guarantee that the 'output' option name will always be
available. It might be better to stay generic with the header and
instead create the reference in the option description like:

 -o, --output <list>    columns to display (see Columns:)

 Columns:
      SOURCE  source device
      ...

This would also keep the Columns header format consistent with the others.

On a somewhat related note; in recent discussion I've been trying to
promote the idea of using consistent language. For example, with all of
the synonyms: output, show, to stdout, display, print, etc. I think it
would be helpful to both users and translators to choose one to be used
consistently. Especially for technical writing it is important to use
consistent terms.

An idea from the Linux man-pages project is that man-pages.7 has a list
of preferred terms/spellings; perhaps util-linux could have a list of
preferred terms to be used in documentation and message strings?

We also might want to consider replacing Documentation/howto-man-page.txt
with a link to, or a copy of, man-pages.7. Michael and company have
added a lot to it in recent times.


> 
>     Karel
> 
> 

Re: [PATCH 0/4] pull request

[Karel Zak]

On Mon, Jun 26, 2017 at 09:47:42AM -0400, J William Piggott wrote:
> 
> 
> On 06/26/2017 04:27 AM, Karel Zak wrote:
> > On Sun, Jun 25, 2017 at 05:45:56PM -0400, J William Piggott wrote:
> >>
> >> * Rudi didn't like cluttering boilerplate.c with seldom used USAGE_*
> >>   constants and I don't disagree with that point. I do think they should
> >>   be in the file for new contributor discovery purposes. As a compromise
> >>   I added the missing ones as a comment.
> >>
> >> * the newly added USAGE_COLUMNS could be used in disk-utils/fdisk-list.c:432
> >>   if Karel wants to drop the ' (for -o)'. I did not change it.
> > 
> > I think USAGE_COLUMNS should be good enough everywhere and the
> > additional notes (like ' (for -o)') are unnecessary.
> > 
> > Maybe we can change the text to "Available output columns:" to make it
> > more specific for readers.
> 
> Since we cannot guarantee that the 'output' option name will always be
> available.

I have already pushed "Available output columns:" :-) 

The "output" does not mean any option in this case.

> It might be better to stay generic with the header and
> instead create the reference in the option description like:
> 
>  -o, --output <list>    columns to display (see Columns:)
> 
>  Columns:
>       SOURCE  source device
>       ...

Anyway, I like this "see Columns:" idea. Go ahead and send patch.

> On a somewhat related note; in recent discussion I've been trying to
> promote the idea of using consistent language. For example, with all of
> the synonyms: output, show, to stdout, display, print, etc. I think it
> would be helpful to both users and translators to choose one to be used
> consistently. Especially for technical writing it is important to use
> consistent terms.
> 
> An idea from the Linux man-pages project is that man-pages.7 has a list
> of preferred terms/spellings; perhaps util-linux could have a list of
> preferred terms to be used in documentation and message strings?

Sounds good. (but I hope we will have no endless "bike-shed
color" discussion about the terms)

> We also might want to consider replacing Documentation/howto-man-page.txt
> with a link to, or a copy of, man-pages.7. Michael and company have
> added a lot to it in recent times.

Documentation/howto-man-page.txt is a template, if you want to write new
tool than it should be good enough to cp(1) this template and use it.
I'd like to keep it there.

We can rename the file to Documentation/boilerplate.1 and rewrite
Documentation/howto-man-page.txt to the real how-to with link to the
Michal's man-pages.7.

    Karel

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