[src/trunk]: src/dist/bzip2 Convert to mdoc. Reorder content to sort flags an...

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/92c63eff0e19
branches:  trunk
changeset: 754845:92c63eff0e19
user:      wiz <wiz%NetBSD.org@localhost>
date:      Fri May 14 09:16:17 2010 +0000

description:
Convert to mdoc. Reorder content to sort flags and sections.

diffstat:

 dist/bzip2/bzip2.1 |  885 ++++++++++++++++++++++++++++------------------------
 1 files changed, 471 insertions(+), 414 deletions(-)

diffs (truncated from 928 to 300 lines):

diff -r 8d19d8e09fa6 -r 92c63eff0e19 dist/bzip2/bzip2.1
--- a/dist/bzip2/bzip2.1        Fri May 14 08:31:38 2010 +0000
+++ b/dist/bzip2/bzip2.1        Fri May 14 09:16:17 2010 +0000
@@ -1,453 +1,510 @@
-.\"    $NetBSD: bzip2.1,v 1.5 2010/05/14 01:52:48 joerg Exp $
+.\"    $NetBSD: bzip2.1,v 1.6 2010/05/14 09:16:17 wiz Exp $
 .\"
-.TH BZIP2 1
-.SH NAME
-bzip2, bunzip2 \- a block-sorting file compressor, v1.0.5
-.br
-bzcat \- decompresses files to stdout
-.br
-bzip2recover \- recovers data from damaged bzip2 files
-
-.SH SYNOPSIS
-.B bzip2
-.RB [ " \-cdfkqstvzVL123456789 " ]
-[
-.I "filenames \&..."
-]
-.br
-.B bunzip2
-.RB [ " \-fkvsVL " ]
-[ 
-.I "filenames \&..."
-]
-.br
-.B bzcat
-.RB [ " \-s " ]
-[ 
-.I "filenames \&..."
-]
-.br
-.B bzip2recover
-.I "filename"
-
-.SH DESCRIPTION
-.I bzip2
+.Dd May 14, 2010
+.Dt BZIP2 1
+.Os
+.Sh NAME
+.Nm bzip2 ,
+.Nm bunzip2 ,
+.Nm bzcat ,
+.Nm bzip2recover
+.Nd block-sorting file compressor
+.Sh SYNOPSIS
+.Nm bzip2
+.Op Fl 123456789cdfkLqstVvz
+.Op Ar filename Ar
+.Pp
+.Nm bunzip2
+.Op Fl fkLVvs
+.Op Ar filename Ar
+.Pp
+.Nm bzcat
+.Op Fl s
+.Op Ar filename Ar
+.Pp
+.Nm bzip2recover
+.Ar filename
+.Sh DESCRIPTION
+.Nm bzip2
 compresses files using the Burrows-Wheeler block sorting
-text compression algorithm, and Huffman coding.  Compression is
-generally considerably better than that achieved by more conventional
-LZ77/LZ78-based compressors, and approaches the performance of the PPM
-family of statistical compressors.
-
-The command-line options are deliberately very similar to 
-those of 
-.I GNU gzip, 
+text compression algorithm, and Huffman coding.
+Compression is generally considerably better than that achieved by
+more conventional LZ77/LZ78-based compressors, and approaches the
+performance of the PPM family of statistical compressors.
+.Pp
+.Nm bzcat
+decompresses files to stdout, and
+.Nm bzip2recover
+recovers data from damaged bzip2 files.
+.Pp
+The command-line options are deliberately very similar to
+those of
+.Xr gzip 1 ,
 but they are not identical.
-
-.I bzip2
-expects a list of file names to accompany the
-command-line flags.  Each file is replaced by a compressed version of
-itself, with the name "original_name.bz2".  
-Each compressed file
-has the same modification date, permissions, and, when possible,
-ownership as the corresponding original, so that these properties can
-be correctly restored at decompression time.  File name handling is
-naive in the sense that there is no mechanism for preserving original
-file names, permissions, ownerships or dates in filesystems which lack
-these concepts, or have serious file name length restrictions, such as
-MS-DOS.
-
-.I bzip2
+.Pp
+.Nm bzip2
+expects a list of file names to accompany the command-line flags.
+Each file is replaced by a compressed version of
+itself, with the name
+.Dq Pa original_name.bz2 .
+Each compressed file has the same modification date, permissions, and,
+when possible, ownership as the corresponding original, so that these
+properties can be correctly restored at decompression time.
+File name handling is naive in the sense that there is no mechanism
+for preserving original file names, permissions, ownerships or dates
+in filesystems which lack these concepts, or have serious file name
+length restrictions, such as
+.Tn MS-DOS .
+.Nm bzip2
 and
-.I bunzip2
-will by default not overwrite existing
-files.  If you want this to happen, specify the \-f flag.
-
+.Nm bunzip2
+will by default not overwrite existing files.
+If you want this to happen, specify the
+.Fl f
+flag.
+.Pp
 If no file names are specified,
-.I bzip2
-compresses from standard
-input to standard output.  In this case,
-.I bzip2
-will decline to
-write compressed output to a terminal, as this would be entirely
-incomprehensible and therefore pointless.
-
-.I bunzip2
+.Nm bzip2
+compresses from standard input to standard output.
+In this case,
+.Nm bzip2
+will decline to write compressed output to a terminal, as this would
+be entirely incomprehensible and therefore pointless.
+.Pp
+.Nm bunzip2
 (or
-.I bzip2 \-d) 
-decompresses all
-specified files.  Files which were not created by 
-.I bzip2
-will be detected and ignored, and a warning issued.  
-.I bzip2
-attempts to guess the filename for the decompressed file 
+.Nm bzip2 Fl d )
+decompresses all specified files.
+Files which were not created by
+.Nm bzip2
+will be detected and ignored, and a warning issued.
+.Nm bzip2
+attempts to guess the filename for the decompressed file
 from that of the compressed file as follows:
-
-       filename.bz2    becomes   filename
-       filename.bz     becomes   filename
-       filename.tbz2   becomes   filename.tar
-       filename.tbz    becomes   filename.tar
-       anyothername    becomes   anyothername.out
-
-If the file does not end in one of the recognised endings, 
-.I .bz2, 
-.I .bz, 
-.I .tbz2
+.Bl -column "filename.tbz2" "becomes" -offset indent
+.It Pa filename.bz2  Ta becomes Ta Pa filename
+.It Pa filename.bz   Ta becomes Ta Pa filename
+.It Pa filename.tbz2 Ta becomes Ta Pa filename.tar
+.It Pa filename.tbz  Ta becomes Ta Pa filename.tar
+.It Pa anyothername  Ta becomes Ta Pa anyothername.out
+.El
+.Pp
+If the file does not end in one of the recognised endings,
+.Pa .bz2 ,
+.Pa .bz ,
+.Pa .tbz2 ,
 or
-.I .tbz, 
-.I bzip2 
-complains that it cannot
-guess the name of the original file, and uses the original name
-with
-.I .out
+.Pa .tbz ,
+.Nm bzip2
+complains that it cannot guess the name of the original file, and uses
+the original name with
+.Pa .out
 appended.
-
-As with compression, supplying no
-filenames causes decompression from 
+.Pp
+As with compression, supplying no filenames causes decompression from
 standard input to standard output.
-
-.I bunzip2 
-will correctly decompress a file which is the
-concatenation of two or more compressed files.  The result is the
-concatenation of the corresponding uncompressed files.  Integrity
-testing (\-t) 
-of concatenated 
-compressed files is also supported.
-
+.Pp
+.Nm bunzip2
+will correctly decompress a file which is the concatenation of two or
+more compressed files.
+The result is the concatenation of the corresponding uncompressed
+files.
+Integrity testing
+.Pq Fl t
+of concatenated compressed files is also supported.
+.Pp
 You can also compress or decompress files to the standard output by
-giving the \-c flag.  Multiple files may be compressed and
-decompressed like this.  The resulting outputs are fed sequentially to
-stdout.  Compression of multiple files 
-in this manner generates a stream
-containing multiple compressed file representations.  Such a stream
-can be decompressed correctly only by
-.I bzip2 
-version 0.9.0 or
-later.  Earlier versions of
-.I bzip2
+giving the
+.Fl c
+flag.
+Multiple files may be compressed and decompressed like this.
+The resulting outputs are fed sequentially to stdout.
+Compression of multiple files in this manner generates a stream
+containing multiple compressed file representations.
+Such a stream can be decompressed correctly only by
+.Nm bzip2
+version 0.9.0 or later.
+Earlier versions of
+.Nm bzip2
 will stop after decompressing
 the first file in the stream.
-
-.I bzcat
+.Pp
+.Nm bzcat
 (or
-.I bzip2 -dc) 
-decompresses all specified files to
-the standard output.
-
-.I bzip2
-will read arguments from the environment variables
-.I BZIP2
-and
-.I BZIP,
-in that order, and will process them
-before any arguments read from the command line.  This gives a 
-convenient way to supply default arguments.
-
-Compression is always performed, even if the compressed 
-file is slightly
-larger than the original.  Files of less than about one hundred bytes
-tend to get larger, since the compression mechanism has a constant
-overhead in the region of 50 bytes.  Random data (including the output
-of most file compressors) is coded at about 8.05 bits per byte, giving
-an expansion of around 0.5%.
-
-As a self-check for your protection, 
-.I 
-bzip2
-uses 32-bit CRCs to
-make sure that the decompressed version of a file is identical to the
-original.  This guards against corruption of the compressed data, and
-against undetected bugs in
-.I bzip2
-(hopefully very unlikely).  The
-chances of data corruption going undetected is microscopic, about one
-chance in four billion for each file processed.  Be aware, though, that
-the check occurs upon decompression, so it can only tell you that
-something is wrong.  It can't help you 
-recover the original uncompressed
-data.  You can use 
-.I bzip2recover
+.Nm bzip2 Fl dc )
+decompresses all specified files to the standard output.
+.Pp
+Compression is always performed, even if the compressed file is
+slightly larger than the original.
+Files of less than about one hundred bytes tend to get larger, since
+the compression mechanism has a constant overhead in the region of 50
+bytes.
+Random data (including the output of most file compressors) is coded