docs: align hexdump.1 with howto-man-page.txt

Signed-off-by: Sami Kerola <kerolasa@iki.fi>

1 files changed, 259 insertions, 266 deletions

diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1
index ce783c1c5..cbb14fb85 100644
--- a/text-utils/hexdump.1
+++ b/text-utils/hexdump.1
@@ -31,319 +31,312 @@
 .\"
 .\"	from: @(#)hexdump.1	8.2 (Berkeley) 4/18/94
 .\"
-.Dd July 2009 "  "
-.Dt HEXDUMP(1) "" "User Commands"
-.Os util-linux
-.Sh NAME
-.Nm hexdump
-.Nd display file contents in ascii, decimal, hexadecimal, or octal
-.Sh SYNOPSIS
-.Nm
-.Op Fl bcCdovx
-.Bk -words
-.Op Fl e Ar format_string
-.Ek
-.Bk -words
-.Op Fl f Ar format_file
-.Ek
-.Bk -words
-.Op Fl n Ar length
-.Ek
-.Bk -words
-.Op Fl s Ar skip
-.Ek
-.Ar file ...
-.Sh DESCRIPTION
+.TH HEXDUMP "1" "September 2011" "util-linux" "User Commands"
+.SH NAME
+hexdump \- display file contents in ascii, decimal, hexadecimal, or octal
+.SH SYNOPSIS
+.B hexdump
+[options] file [...]
+.SH DESCRIPTION
 The
-.Nm
+.B hexdump
 utility is a filter which displays the specified files, or
 standard input if no files are specified, in a user-specified
 format.
-.Pp
-The options are as follows:
-.Bl -tag -width Fl
-.It Fl b
-.Em One-byte octal display .
-Display the input offset in hexadecimal, followed by sixteen
-space-separated, three-column, zero-filled bytes of input data,
-in octal, per line.
-.It Fl c
-.Em One-byte character display .
-Display the input offset in hexadecimal, followed by sixteen
-space-separated, three-column, space-filled characters of input
-data per line.
-.It Fl C
-.Em Canonical hex+ASCII display .
-Display the input offset in hexadecimal, followed by sixteen
-space-separated, two-column, hexadecimal bytes, followed by the
-same sixteen bytes in %_p format enclosed in ``|'' characters.
-.It Fl d
-.Em Two-byte decimal display .
-Display the input offset in hexadecimal, followed by eight
-space-separated, five-column, zero-filled, two-byte units
+.SH OPTIONS
+.TP
+.B \-b
+\fIOne-byte octal display\fR.  Display the input offset in hexadecimal,
+followed by sixteen space-separated, three-column, zero-filled bytes of input
+data, in octal, per line.
+.TP
+.B \-c
+\fIOne-byte character display\fR.  Display the input offset in hexadecimal,
+followed by sixteen space-separated, three-column, space-filled characters of
+input data per line.
+.TP
+.B \-C
+\fICanonical hex+ASCII display\fR.  Display the input offset in hexadecimal,
+followed by sixteen space-separated, two-column, hexadecimal bytes, followed
+by the same sixteen bytes in
+.B %_p
+format enclosed in
+.RB ' | '
+characters.
+.TP
+.B \-d
+\fITwo-byte decimal display\fR.  Display the input offset in hexadecimal,
+followed by eight space-separated, five-column, zero-filled, two-byte units
 of input data, in unsigned decimal, per line.
-.It Fl e Ar format_string
+.TP
+.BI \-e \ format_string
 Specify a format string to be used for displaying data.
-.It Fl f Ar format_file
+.TP
+.BI \-f \ format_file
 Specify a file that contains one or more newline separated format strings.
-Empty lines and lines whose first non-blank character is a hash mark
-.Pf ( Cm \&# )
+Empty lines and lines whose first non-blank character is a hash mark (\&#)
 are ignored.
-.It Fl n Ar length
+.TP
+.BI \-n \ length
 Interpret only
-.Ar length
+.I length
 bytes of input.
-.It Fl o
-.Em Two-byte octal display .
-Display the input offset in hexadecimal, followed by eight
-space-separated, six-column, zero-filled, two-byte quantities of
-input data, in octal, per line.
-.It Fl s Ar offset
+.TP
+.B \-o
+\fITwo-byte octal display\fR.  Display the input offset in hexadecimal,
+followed by eight space-separated, six-column, zero-filled, two-byte
+quantities of input data, in octal, per line.
+.TP
+.BI \-s \ offset
 Skip
-.Ar offset
-bytes from the beginning of the input.
-By default,
-.Ar offset
-is interpreted as a decimal number.
-With a leading
-.Cm 0x
+.I offset
+bytes from the beginning of the input.  By default,
+.I offset
+is interpreted as a decimal number.  With a leading
+.B 0x
 or
-.Cm 0X ,
-.Ar offset
-is interpreted as a hexadecimal number,
-otherwise, with a leading
-.Cm 0 ,
-.Ar offset
-is interpreted as an octal number.
-Appending the character
-.Cm b ,
-.Cm k ,
+.BR 0X ,
+.I offset
+is interpreted as a hexadecimal number, otherwise, with a leading
+.BR 0 ,
+.I offset
+is interpreted as an octal number.  Appending the character
+.BR b ,
+.BR k ,
 or
-.Cm m
+.B m
 to
-.Ar offset
+.I offset
 causes it to be interpreted as a multiple of
-.Li 512 ,
-.Li 1024 ,
+.IR 512 ,
+.IR 1024 ,
 or
-.Li 1048576 ,
+.IR 1048576 ,
 respectively.
-.It Fl v
+.TP
+.B \-v
 The
-.Fl v
+.B \-v
 option causes
-.Nm
-to display all input data.
-Without the
-.Fl v
-option, any number of groups of output lines which would be
-identical to the immediately preceding group of output lines (except
-for the input offsets), are replaced with a line comprised of a
-single asterisk.
-.It Fl x
-.Em Two-byte hexadecimal display .
-Display the input offset in hexadecimal, followed by eight
-space-separated, four-column, zero-filled, two-byte quantities of
-input data, in hexadecimal, per line.
-.El
-.Pp
+.B hexdump
+to display all input data.  Without the
+.B \-v
+option, any number of groups of output lines which would be identical to the
+immediately preceding group of output lines (except for the input offsets),
+are replaced with a line comprised of a single asterisk.
+.TP
+.B \-x
+\fITwo-byte hexadecimal display\fR.  Display the input offset in hexadecimal,
+followed by eight space-separated, four-column, zero-filled, two-byte
+quantities of input data, in hexadecimal, per line.
+.PP
 For each input file,
-.Nm
-sequentially copies the input to standard output, transforming the
-data according to the format strings specified by the
-.Fl e
+.B hexdump
+sequentially copies the input to standard output, transforming the data
+according to the format strings specified by the
+.B \-e
 and
-.Fl f
+.B \-f
 options, in the order that they were specified.
-.Ss Formats
-A format string contains any number of format units, separated by
-whitespace.
-A format unit contains up to three items: an iteration count, a byte
-count, and a format.
-.Pp
-The iteration count is an optional positive integer, which defaults to
-one.
+.SH FORMATS
+A format string contains any number of format units, separated by whitespace.
+A format unit contains up to three items: an iteration count, a byte count,
+and a format.
+.PP
+The iteration count is an optional positive integer, which defaults to one.
 Each format is applied iteration count times.
-.Pp
-The byte count is an optional positive integer.
-If specified it defines the number of bytes to be interpreted by
-each iteration of the format.
-.Pp
-If an iteration count and/or a byte count is specified, a single slash
-must be placed after the iteration count and/or before the byte count
-to disambiguate them.
-Any whitespace before or after the slash is ignored.
-.Pp
-The format is required and must be surrounded by double quote
-(" ") marks.
+.PP
+The byte count is an optional positive integer.  If specified it defines the
+number of bytes to be interpreted by each iteration of the format.
+.PP
+If an iteration count and/or a byte count is specified, a single slash must
+be placed after the iteration count and/or before the byte count to
+disambiguate them.  Any whitespace before or after the slash is ignored.
+.PP
+The format is required and must be surrounded by double quote (" ") marks.
 It is interpreted as a fprintf-style format string (see
-.Xr fprintf 3 ) ,
-with the
-following exceptions:
-.Bl -bullet -offset indent
-.It
+.BR fprintf (3),
+with the following exceptions:
+.TP
+1.
 An asterisk (*) may not be used as a field width or precision.
-.It
+.TP
+2.
 A byte count or field precision
-.Em is
-required for each ``s'' conversion
-character (unlike the
-.Xr fprintf 3
+.I is
+required for each
+.B s
+conversion character (unlike the
+.BR fprintf (3)
 default which prints the entire string if the precision is unspecified).
-.It
-The conversion characters ``h'', ``l'', ``n'', ``p'' and ``q'' are
-not supported.
-.It
-The single character escape sequences
-described in the C standard are supported:
-.Bd -ragged -offset indent -compact
-.Bl -column <alert_character>
-.It NUL	\e0
-.It <alert character>	\ea
-.It <backspace>	\eb
-.It <form-feed>	\ef
-.It <newline>	\en
-.It <carriage return>	\er
-.It <tab>	\et
-.It <vertical tab>	\ev
-.El
-.Ed
-.El
-.Pp
+.TP
+3.
+The conversion characters
+.BR h , \ l , \ n , \ p ,
+.RB  and \ q
+are not supported.
+.TP
+4.
+The single character escape sequences described in the C standard are
+supported:
+.PP
+.RS 13
+.PD 0
+.TP 21
+NULL
+\e0
+.TP
+<alert character>
+\ea
+.TP
+<backspace>
+\eb
+.TP
+<form-feed>
+\ef
+.TP
+<newline>
+\en
+.TP
+<carriage return>
+\er
+.TP
+<tab>
+\et
+.TP
+<vertical tab>
+\ev
+.PD
+.RE
+.PP
+.SS Conversion strings
 The
-.Nm
-utility also supports the following additional conversion strings:
-.Bl -tag -width Fl
-.It Cm \&_a Ns Op Cm dox
-Display the input offset, cumulative across input files, of the
-next byte to be displayed.
-The appended characters
-.Cm d ,
-.Cm o ,
+.B hexdump
+utility also supports the following additional conversion strings.
+.TP
+.B \&_a[dox]
+Display the input offset, cumulative across input files, of the next byte to
+be displayed.  The appended characters
+.BR d ,
+.BR o ,
 and
-.Cm x
-specify the display base
-as decimal, octal or hexadecimal respectively.
-.It Cm \&_A Ns Op Cm dox
+.B x
+specify the display base as decimal, octal or hexadecimal respectively.
+.TP
+.B \&_A[dox]
 Identical to the
-.Cm \&_a
-conversion string except that it is only performed
-once, when all of the input data has been processed.
-.It Cm \&_c
-Output characters in the default character set.
-Nonprinting characters are displayed in three-character, zero-padded
-octal, except for those representable by standard escape notation
-(see above),
-which are displayed as two-character strings.
-.It Cm _p
-Output characters in the default character set.
-Nonprinting characters are displayed as a single
-.Dq Cm \&. .
-.It Cm _u
+.B \&_a
+conversion string except that it is only performed once, when all of the
+input data has been processed.
+.TP
+.B \&_c
+Output characters in the default character set.  Nonprinting characters are
+displayed in three-character, zero-padded octal, except for those
+representable by standard escape notation (see above), which are displayed as
+two-character strings.
+.TP
+.B \&_p
+Output characters in the default character set.  Nonprinting characters are
+displayed as a single
+.RB ' \&. '.
+.TP
+.B \&_u
 Output US ASCII characters, with the exception that control characters are
-displayed using the following, lower-case, names.
-Characters greater than 0xff, hexadecimal, are displayed as hexadecimal
-strings.
-.Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
-.It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
-.It \&006\ ack\t007\ bel\t008\ bs\t009\ ht\t00A\ lf\t00B\ vt
-.It \&00C\ ff\t00D\ cr\t00E\ so\t00F\ si\t010\ dle\t011\ dc1
-.It \&012\ dc2\t013\ dc3\t014\ dc4\t015\ nak\t016\ syn\t017\ etb
-.It \&018\ can\t019\ em\t01A\ sub\t01B\ esc\t01C\ fs\t01D\ gs
-.It \&01E\ rs\t01F\ us\t0FF\ del
-.El
-.El
-.Pp
+displayed using the following, lower-case, names.  Characters greater than
+0xff, hexadecimal, are displayed as hexadecimal strings.
+.PP
+.nf
+          000 nul  001 soh  002 stx  003 etx  004 eot  005 enq
+          006 ack  007 bel  008 bs   009 ht   00A lf   00B vt
+          00C ff   00D cr   00E so   00F si   010 dle  011 dc1
+          012 dc2  013 dc3  014 dc4  015 nak  016 syn  017 etb
+          018 can  019 em   01A sub  01B esc  01C fs   01D gs
+          01E rs   01F us   0FF del
+.nf
+.SS Counters
 The default and supported byte counts for the conversion characters
 are as follows:
-.Bl -tag -width  "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
-.It Li \&%_c , \&%_p , \&%_u , \&%c
+.TP
+.BR \&%_c , \ \&%_p , \ \&%_u , \ \&%c
 One byte counts only.
-.It Xo
-.Li \&%d , \&%i , \&%o ,
-.Li \&%u , \&%X , \&%x
-.Xc
+.TP
+.BR \&%d , \ \&%i , \ \&%o , \ \&%u , \ \&%X , \ \&%x
 Four byte default, one, two and four byte counts supported.
-.It Xo
-.Li \&%E , \&%e , \&%f ,
-.Li \&%G , \&%g
-.Xc
+.TP
+.BR \&%E , \ \&%e , \ \&%f , \ \&%G , \ \&%g
 Eight byte default, four byte counts supported.
-.El
-.Pp
-The amount of data interpreted by each format string is the sum of the
-data required by each format unit, which is the iteration count times the
-byte count, or the iteration count times the number of bytes required by
-the format if the byte count is not specified.
-.Pp
-The input is manipulated in ``blocks'', where a block is defined as the
-largest amount of data specified by any format string.
-Format strings interpreting less than an input block's worth of data,
-whose last format unit both interprets some number of bytes and does
-not have a specified iteration count, have the iteration count
-incremented until the entire input block has been processed or there
-is not enough data remaining in the block to satisfy the format string.
-.Pp
+.PP
+The amount of data interpreted by each format string is the sum of the data
+required by each format unit, which is the iteration count times the byte
+count, or the iteration count times the number of bytes required by the
+format if the byte count is not specified.
+.PP
+The input is manipulated in
+.IR blocks ,
+where a block is defined as the largest amount of data specified by any
+format string.  Format strings interpreting less than an input block's worth
+of data, whose last format unit both interprets some number of bytes and does
+not have a specified iteration count, have the iteration count incremented
+until the entire input block has been processed or there is not enough data
+remaining in the block to satisfy the format string.
+.PP
 If, either as a result of user specification or
-.Nm
+.B hexdump
 modifying the iteration count as described above, an iteration count is
-greater than one, no trailing whitespace characters are output
-during the last iteration.
-.Pp
+greater than one, no trailing whitespace characters are output during the
+last iteration.
+.PP
 It is an error to specify a byte count as well as multiple conversion
-characters or strings unless all but one of the conversion characters
-or strings is
-.Cm \&_a
+characters or strings unless all but one of the conversion characters or
+strings is
+.B \&_a
 or
-.Cm \&_A .
-.Pp
+.BR \&_A .
+.PP
 If, as a result of the specification of the
-.Fl n
-option or end-of-file being reached, input data only partially
-satisfies a format string, the input block is zero-padded sufficiently
-to display all available data (i.e. any format units overlapping the
-end of data will display some number of the zero bytes).
-.Pp
-Further output by such format strings is replaced by an equivalent
-number of spaces.
-An equivalent number of spaces is defined as the number of spaces
+.B \-n
+option or end-of-file being reached, input data only partially satisfies a
+format string, the input block is zero-padded sufficiently to display all
+available data (i.e. any format units overlapping the end of data will
+display some number of the zero bytes).
+.PP
+Further output by such format strings is replaced by an equivalent number of
+spaces.  An equivalent number of spaces is defined as the number of spaces
 output by an
-.Cm s
-conversion character with the same field width
-and precision as the original conversion character or conversion
-string but with any
-.Dq Li \&+ ,
-.Dq \&\ \& ,
-.Dq Li \&#
-conversion flag characters
-removed, and referencing a NULL string.
-.Pp
+.B s
+conversion character with the same field width and precision as the original
+conversion character or conversion string but with any
+.RB ' \&+ ',
+\' \',
+.RB ' \&# '
+conversion flag characters removed, and referencing a NULL string.
+.PP
 If no format strings are specified, the default display is equivalent
 to specifying the
-.Fl x
+.B \-x
 option.
-.Pp
-.Nm
+.SH "EXIT STATUS"
+.B hexdump
 exits 0 on success and >0 if an error occurred.
-.Sh EXAMPLES
+.SH EXAMPLES
 Display the input in perusal format:
-.Bd -literal -offset indent
-"%06.6_ao "  12/1 "%3_u "
-"\et\et" "%_p "
-"\en"
-.Ed
-.Pp
+.nf
+   "%06.6_ao "  12/1 "%3_u "
+   "\et\et" "%_p "
+   "\en"
+.nf
+.PP
 Implement the \-x option:
-.Bd -literal -offset indent
-"%07.7_Ax\en"
-"%07.7_ax  " 8/2 "%04x " "\en"
-.Ed
-.Sh STANDARDS
+.nf
+   "%07.7_Ax\en"
+   "%07.7_ax  " 8/2 "%04x " "\en"
+.nf
+.SH STANDARDS
 The
-.Nm
-utility is expected to be
-.St -p1003.2
-compatible.
-.Sh AVAILABILITY
+.B hexdump
+utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
+.SH AVAILABILITY
 The hexdump command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
+.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
+Linux Kernel Archive
+.UE .