Re: Bug#514675: coreutils: id manpage is too short on details

[Jim Meyering]

"brian m. carlson" <address@hidden> wrote:
> Package: coreutils
> Version: 6.10-6
> Severity: normal
>
> The manpage for id does not describe what information it prints.  It
> should state that by default, the information printed is the username
> and userid, default/current group name and group id, and the list of
> groups (and the group ids) to which that user belongs, instead of merely
> stating "Without any OPTION, print some useful set of identified [sic]
> information."
>
> The description should be changed from "Print information for USERNAME,
> or the current user." to "Print information about the user and groups
> for the user specified by USERNAME, or the current user if USERNAME is
> not specified."

Good idea.

> A user who has never heard of id should be able to determine how to
> properly use it by looking solely at the manual page.  In its current
> state, that's apparently not the case; hence, this bug.
>
> If you specify whether you'd like the manpage in man, mdoc, or DocBook
> 5.0 format, I'll happily provide you with a non-autogenerated manpage
> with useful information.

Thanks!  If you'd like to contribute more to coreutils,
instructions/guidelines are here:

  http://git.sv.gnu.org/cgit/coreutils.git/plain/HACKING

I'll soon push the following change upstream:


>From 4ca909e06dbc8dfa998b70d28a8fbf95991c12b1 Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Sat, 14 Feb 2009 09:09:17 +0100
Subject: [PATCH] doc: id: make --help and .man more descriptive

* src/id.c (usage): Improve description, based on a suggestion
from Brian M. Carlson in http://bugs.debian.org/514675
* man/id.x: Use a better one-liner, based on the one at top of id.c.
---
 THANKS   |    1 +
 man/id.x |    2 +-
 src/id.c |    3 ++-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/THANKS b/THANKS
index a3f9801..bedb01a 100644
--- a/THANKS
+++ b/THANKS
@@ -82,6 +82,7 @@ Bob Proulx                          address@hidden
 Branden Robinson                    address@hidden
 Brendan O'Dea                       address@hidden
 Brian Kimball                       address@hidden
+Brian M. Carlson                    address@hidden
 Brian Silverman                     address@hidden
 Brian Youmans                       address@hidden
 Bruce Korb                          address@hidden
diff --git a/man/id.x b/man/id.x
index 4c990ac..d55b326 100644
--- a/man/id.x
+++ b/man/id.x
@@ -1,4 +1,4 @@
 [NAME]
-id \- print user identity
+id \- print real and effective user and group IDs
 [DESCRIPTION]
 .\" Add any additional description here
diff --git a/src/id.c b/src/id.c
index 05ad2d8..78f78e0 100644
--- a/src/id.c
+++ b/src/id.c
@@ -81,7 +81,8 @@ usage (int status)
     {
       printf (_("Usage: %s [OPTION]... [USERNAME]\n"), program_name);
       fputs (_("\
-Print information for USERNAME, or the current user.\n\
+Print user and group information for the specified USERNAME,\n\
+or (when USERNAME omitted) for the current user.\n\
 \n\
   -a              ignore, for compatibility with other versions\n\
   -Z, --context   print only the security context of the current user\n\
--
1.6.2.rc0.234.g2cc0b3