Subject: bug#13280: closed (Re: bug#13280: od 8.19: inappropriate formatting of the man pages)

From: [email-masked] (GNU bug Tracking System)
Date: Thu, 27 Dec 2012 11:44:02 +0000

Your bug report

#13280: od 8.19: inappropriate formatting of the man pages

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
13280: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=13280
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#13280: od 8.19: inappropriate formatting of the man pages
From: Pádraig Brady <[email-masked]>
To: Akim Demaille <[email-masked]>
Cc: [email-masked]
Date: Thu, 27 Dec 2012 11:42:15 +0000
List-Id: <debbugs-submit.debbugs.gnu.org>

On 12/26/2012 07:43 AM, Akim Demaille wrote:
> (Wow, I had never realized that applying --program-prefix=g on
> od results in invoking god).
>
> You might consider this a bug, or not.  Sorry for the noise if
> you don't.
>
> "man od" (well, in my case, yet another interesting command to
> type, with deep philosophical meaning) includes a section-like
> (in bold) title for:
>
>     Traditional format specifications may be intermixed; they accumulate:
>
> but it does not for:
>
>         TYPE is made up of one or more of these specifications:
>
> (also the next paragraph, "RADIX is d for…" seems to belong
> to the "TYPE" section, but it does not.  So maybe another section-like
> separation would be nice).

Yes the grouping of that info wasn't optimum.
I've adjusted things a bit in the attached patch,
and the result can be seen in the attached pdf generated with:
   man -t man/od.1 | ps2pdf - > od.pdf
Note since people like examples, as part of this I've added
an EXAMPLES section, that shows how to output a hexdump with od.

thanks,
Pádraig.
>From 4ecd55692804867e6dca19b4c317565c8d5e44b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email-masked]>
Date: Thu, 27 Dec 2012 04:14:14 +0000
Subject: [PATCH] doc: improve od --help and man page

* src/od.c: Redorder the information output by --help
to ease interpretation and so that appropriate sections
are generated by help2man.
* doc/coreutils.texi (od invocation): Fix an incorrect
reference to @var{n}, which should be @var{bytes}.
* man/od.x: Add an "Examples" section, and move the
default od format to there, and add a commonly required
format to generate hexdumps.
Reported by Akim Demaille.
---
 doc/coreutils.texi |    2 +-
 man/od.x           |    7 ++++++
 src/od.c           |   53 +++++++++++++++++++++++++++++----------------------
 3 files changed, 38 insertions(+), 24 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index bed3553..3c970d7 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -1884,7 +1884,7 @@ followed by a zero byte (ASCII @sc{nul}).
 Prefixes and suffixes on @var{bytes} are interpreted as for the
 @option{-j} option.
 
-If @var{n} is omitted with @option{--strings}, the default is 3.
+If @var{bytes} is omitted with @option{--strings}, the default is 3.
 
 @item -t @var{type}
 @itemx --format=@var{type}
diff --git a/man/od.x b/man/od.x
index c913f80..b98beec 100644
--- a/man/od.x
+++ b/man/od.x
@@ -2,3 +2,10 @@
 od \- dump files in octal and other formats
 [DESCRIPTION]
 .\" Add any additional description here
+[EXAMPLES]
+.TP
+.B od -A x -t x1z -v
+Display hexdump format output
+.TP
+.B od -A o -t oS -w 16
+The default output format used by od
diff --git a/src/od.c b/src/od.c
index a25f965..c4bc742 100644
--- a/src/od.c
+++ b/src/od.c
@@ -305,24 +305,38 @@ With no FILE, or when FILE is -, read standard input.\n\
 \n\
 "), stdout);
       fputs (_("\
+If first and second call formats both apply, the second format is assumed\n\
+if the last operand begins with + or (if there are 2 operands) a digit.\n\
+An OFFSET operand means -j OFFSET.  LABEL is the pseudo-address\n\
+at first byte printed, incremented when dump is progressing.\n\
+For OFFSET and LABEL, a 0x or 0X prefix indicates hexadecimal;\n\
+suffixes may be . for octal and b for multiply by 512.\n\
+\n\
+"), stdout);
+      fputs (_("\
 All arguments to long options are mandatory for short options.\n\
 "), stdout);
       fputs (_("\
-  -A, --address-radix=RADIX   decide how file offsets are printed\n\
+  -A, --address-radix=RADIX   output format for file offsets.  RADIX is one\n\
+                                of [doxn], for Decimal, Octal, Hex or None\n\
   -j, --skip-bytes=BYTES      skip BYTES input bytes first\n\
 "), stdout);
       fputs (_("\
   -N, --read-bytes=BYTES      limit dump to BYTES input bytes\n\
-  -S BYTES, --strings[=BYTES]  output strings of at least BYTES graphic chars\n\
+  -S BYTES, --strings[=BYTES]  output strings of at least BYTES graphic chars.\
+\n\
+                                3 is implied when BYTES is not specified\n\
   -t, --format=TYPE           select output format or formats\n\
   -v, --output-duplicates     do not use * to mark line suppression\n\
-  -w[BYTES], --width[=BYTES]  output BYTES bytes per output line\n\
-      --traditional           accept arguments in traditional form\n\
+  -w[BYTES], --width[=BYTES]  output BYTES bytes per output line.\n\
+                                32 is implied when BYTES is not specified\n\
+      --traditional           accept arguments in third form above\n\
 "), stdout);
       fputs (HELP_OPTION_DESCRIPTION, stdout);
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       fputs (_("\
 \n\
+\n\
 Traditional format specifications may be intermixed; they accumulate:\n\
   -a   same as -t a,  select named characters, ignoring high-order bit\n\
   -b   same as -t o1, select octal bytes\n\
@@ -339,17 +353,8 @@ Traditional format specifications may be intermixed; they accumulate:\n\
 "), stdout);
       fputs (_("\
 \n\
-If first and second call formats both apply, the second format is assumed\n\
-if the last operand begins with + or (if there are 2 operands) a digit.\n\
-An OFFSET operand means -j OFFSET.  LABEL is the pseudo-address\n\
-at first byte printed, incremented when dump is progressing.\n\
-For OFFSET and LABEL, a 0x or 0X prefix indicates hexadecimal;\n\
-suffixes may be . for octal and b for multiply by 512.\n\
-"), stdout);
-      fputs (_("\
 \n\
 TYPE is made up of one or more of these specifications:\n\
-\n\
   a          named character, ignoring high-order bit\n\
   c          ASCII character or backslash escape\n\
 "), stdout);
@@ -362,24 +367,26 @@ TYPE is made up of one or more of these specifications:\n\
 "), stdout);
       fputs (_("\
 \n\
-SIZE is a number.  For TYPE in doux, SIZE may also be C for\n\
+SIZE is a number.  For TYPE in [doux], SIZE may also be C for\n\
 sizeof(char), S for sizeof(short), I for sizeof(int) or L for\n\
 sizeof(long).  If TYPE is f, SIZE may also be F for sizeof(float), D\n\
 for sizeof(double) or L for sizeof(long double).\n\
 "), stdout);
       fputs (_("\
 \n\
-RADIX is d for decimal, o for octal, x for hexadecimal or n for none.\n\
-BYTES is hexadecimal with 0x or 0X prefix, and may have a multiplier suffix:\n\
-b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,\n\
-GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.\n\
-Adding a z suffix to any type displays printable characters at the end of each\
-\n\
-output line.\n\
+Adding a z suffix to any type displays printable characters at the end of\n\
+each output line.\n\
 "), stdout);
       fputs (_("\
-Option --string without a number implies 3; option --width without a number\n\
-implies 32.  By default, od uses -A o -t oS -w16.\n\
+\n\
+\n\
+BYTES is hex with 0x or 0X prefix, and may have a multiplier suffix:\n\
+  b    512\n\
+  KB   1000\n\
+  K    1024\n\
+  MB   1000*1000\n\
+  M    1024*1024\n\
+and so on for G, T, P, E, Z, Y.\n\
 "), stdout);
       emit_ancillary_info ();
     }
-- 
1.7.6.4

Subject: od 8.19: inappropriate formatting of the man pages
From: Akim Demaille <[email-masked]>
To: [email-masked]
Date: Wed, 26 Dec 2012 08:43:23 +0100
List-Id: <debbugs-submit.debbugs.gnu.org>

(Wow, I had never realized that applying --program-prefix=g on
od results in invoking god).

You might consider this a bug, or not.  Sorry for the noise if
you don't.

"man od" (well, in my case, yet another interesting command to
type, with deep philosophical meaning) includes a section-like
(in bold) title for:

   Traditional format specifications may be intermixed; they accumulate:

but it does not for:

       TYPE is made up of one or more of these specifications:

(also the next paragraph, "RADIX is d for…" seems to belong
to the "TYPE" section, but it does not.  So maybe another section-like
separation would be nice).

in roff-tongue:

…
\fB\-\-version\fR
output version information and exit
.SS "Traditional format specifications may be intermixed; they accumulate:"
.TP
…
.TP
\fB\-x\fR
same as \fB\-t\fR x2, select hexadecimal 2\-byte units
.PP
If first and second call formats both apply, the second format is assumed
if the last operand begins with + or (if there are 2 operands) a digit.
An OFFSET operand means \fB\-j\fR OFFSET.  LABEL is the pseudo\-address
at first byte printed, incremented when dump is progressing.
For OFFSET and LABEL, a 0x or 0X prefix indicates hexadecimal;
suffixes may be . for octal and b for multiply by 512.
.PP
TYPE is made up of one or more of these specifications:
.TP
a
named character, ignoring high\-order bit
.TP
c

Cheers!