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

From: Pádraig Brady <[email-masked]>
Date: Thu, 27 Dec 2012 11:42:15 +0000

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