public inbox for bzip2-devel@sourceware.org
 help / color / mirror / Atom feed
From: Mark Wielaard <mark@klomp.org>
To: bzip2-devel@sourceware.org
Cc: "Anibal Monsalve Salazar" <anibal@debian.org>,
	"Santiago Ruano Rincón" <santiago@debian.org>,
	"Anthony Fok" <foka@debian.org>, "Mark Wielaard" <mark@klomp.org>
Subject: [PATCH 1/3] bzip2.1: remove blank spaces in man page and drop the .PU macro.
Date: Tue, 01 Jan 2019 00:00:00 -0000	[thread overview]
Message-ID: <20190721205419.2904-2-mark@klomp.org> (raw)
In-Reply-To: <20190721205419.2904-1-mark@klomp.org>

Author: Bjarni Ingi Gislason
Bug-Debian: https://bugs.debian.org/675380
---
 bzip2.1 | 138 ++++++++++++++++++++++++++++----------------------------
 1 file changed, 68 insertions(+), 70 deletions(-)

diff --git a/bzip2.1 b/bzip2.1
index 0cbcdab..174b15f 100644
--- a/bzip2.1
+++ b/bzip2.1
@@ -1,4 +1,3 @@
-.PU
 .TH bzip2 1
 .SH NAME
 bzip2, bunzip2 \- a block-sorting file compressor, v1.0.8
@@ -18,13 +17,13 @@ bzip2recover \- recovers data from damaged bzip2 files
 .br
 .B bunzip2
 .RB [ " \-fkvsVL " ]
-[ 
+[
 .I "filenames \&..."
 ]
 .br
 .B bzcat
 .RB [ " \-s " ]
-[ 
+[
 .I "filenames \&..."
 ]
 .br
@@ -39,15 +38,15 @@ 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, 
+The command-line options are deliberately very similar to
+those of
+.I GNU gzip,
 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".  
+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
@@ -74,13 +73,13 @@ incomprehensible and therefore pointless.
 
 .I bunzip2
 (or
-.I bzip2 \-d) 
+.I bzip2 \-d)
 decompresses all
-specified files.  Files which were not created by 
+specified files.  Files which were not created by
 .I bzip2
-will be detected and ignored, and a warning issued.  
+will be detected and ignored, and a warning issued.
 .I bzip2
-attempts to guess the filename for the decompressed file 
+attempts to guess the filename for the decompressed file
 from that of the compressed file as follows:
 
        filename.bz2    becomes   filename
@@ -89,13 +88,13 @@ from that of the compressed file as follows:
        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, 
+If the file does not end in one of the recognised endings,
+.I .bz2,
+.I .bz,
 .I .tbz2
 or
-.I .tbz, 
-.I bzip2 
+.I .tbz,
+.I bzip2
 complains that it cannot
 guess the name of the original file, and uses the original name
 with
@@ -103,25 +102,25 @@ with
 appended.
 
 As with compression, supplying no
-filenames causes decompression from 
+filenames causes decompression from
 standard input to standard output.
 
-.I bunzip2 
+.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 
+testing (\-t)
+of concatenated
 compressed files is also supported.
 
 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 
+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 
+.I bzip2
 version 0.9.0 or
 later.  Earlier versions of
 .I bzip2
@@ -130,7 +129,7 @@ the first file in the stream.
 
 .I bzcat
 (or
-.I bzip2 -dc) 
+.I bzip2 -dc)
 decompresses all specified files to
 the standard output.
 
@@ -140,10 +139,10 @@ will read arguments from the environment variables
 and
 .I BZIP,
 in that order, and will process them
-before any arguments read from the command line.  This gives a 
+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 
+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
@@ -151,9 +150,8 @@ 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
+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
@@ -163,9 +161,9 @@ against undetected bugs in
 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 
+something is wrong.  It can't help you
 recover the original uncompressed
-data.  You can use 
+data.  You can use
 .I bzip2recover
 to try to recover data from
 damaged files.
@@ -183,15 +181,15 @@ to panic.
 Compress or decompress to standard output.
 .TP
 .B \-d --decompress
-Force decompression.  
-.I bzip2, 
-.I bunzip2 
+Force decompression.
+.I bzip2,
+.I bunzip2
 and
-.I bzcat 
+.I bzcat
 are
 really the same program, and the decision about what actions to take is
 done on the basis of which name is used.  This flag overrides that
-mechanism, and forces 
+mechanism, and forces
 .I bzip2
 to decompress.
 .TP
@@ -205,10 +203,10 @@ This really performs a trial decompression and throws away the result.
 .TP
 .B \-f --force
 Force overwrite of output files.  Normally,
-.I bzip2 
+.I bzip2
 will not overwrite
-existing output files.  Also forces 
-.I bzip2 
+existing output files.  Also forces
+.I bzip2
 to break hard links
 to files, which it otherwise wouldn't do.
 
@@ -224,9 +222,9 @@ or decompression.
 Reduce memory usage, for compression, decompression and testing.  Files
 are decompressed and tested using a modified algorithm which only
 requires 2.5 bytes per block byte.  This means any file can be
-decompressed in 2300k of memory, albeit at about half the normal speed.
+decompressed in 2300\ k of memory, albeit at about half the normal speed.
 
-During compression, \-s selects a block size of 200k, which limits
+During compression, \-s selects a block size of 200\ k, which limits
 memory use to around the same figure, at the expense of your compression
 ratio.  In short, if your machine is low on memory (8 megabytes or
 less), use \-s for everything.  See MEMORY MANAGEMENT below.
@@ -244,11 +242,11 @@ information which is primarily of interest for diagnostic purposes.
 Display the software version, license terms and conditions.
 .TP
 .B \-1 (or \-\-fast) to \-9 (or \-\-best)
-Set the block size to 100 k, 200 k ..  900 k when compressing.  Has no
+Set the block size to 100 k, 200 k ...  900 k when compressing.  Has no
 effect when decompressing.  See MEMORY MANAGEMENT below.
-The \-\-fast and \-\-best aliases are primarily for GNU gzip 
+The \-\-fast and \-\-best aliases are primarily for GNU gzip
 compatibility.  In particular, \-\-fast doesn't make things
-significantly faster.  
+significantly faster.
 And \-\-best merely selects the default behaviour.
 .TP
 .B \--
@@ -263,7 +261,7 @@ earlier versions, which was sometimes useful.  0.9.5 and above have an
 improved algorithm which renders these flags irrelevant.
 
 .SH MEMORY MANAGEMENT
-.I bzip2 
+.I bzip2
 compresses large files in blocks.  The block size affects
 both the compression ratio achieved, and the amount of memory needed for
 compression and decompression.  The flags \-1 through \-9
@@ -276,13 +274,13 @@ the file.  Since block sizes are stored in compressed files, it follows
 that the flags \-1 to \-9 are irrelevant to and so ignored
 during decompression.
 
-Compression and decompression requirements, 
+Compression and decompression requirements,
 in bytes, can be estimated as:
 
-       Compression:   400k + ( 8 x block size )
+       Compression:   400\ k + ( 8 x block size )
 
-       Decompression: 100k + ( 4 x block size ), or
-                      100k + ( 2.5 x block size )
+       Decompression: 100\ k + ( 4 x block size ), or
+                      100\ k + ( 2.5 x block size )
 
 Larger block sizes give rapidly diminishing marginal returns.  Most of
 the compression comes from the first two or three hundred k of block
@@ -292,10 +290,10 @@ on small machines.
 It is also important to appreciate that the decompression memory
 requirement is set at compression time by the choice of block size.
 
-For files compressed with the default 900k block size,
+For files compressed with the default 900\ k block size,
 .I bunzip2
 will require about 3700 kbytes to decompress.  To support decompression
-of any file on a 4 megabyte machine, 
+of any file on a 4 megabyte machine,
 .I bunzip2
 has an option to
 decompress using approximately half this amount of memory, about 2300
@@ -311,9 +309,9 @@ Another significant point applies to files which fit in a single block
 amount of real memory touched is proportional to the size of the file,
 since the file is smaller than a block.  For example, compressing a file
 20,000 bytes long with the flag -9 will cause the compressor to
-allocate around 7600k of memory, but only touch 400k + 20000 * 8 = 560
-kbytes of it.  Similarly, the decompressor will allocate 3700k but only
-touch 100k + 20000 * 4 = 180 kbytes.
+allocate around 7600\ k of memory, but only touch 400\ k + 20000 * 8 = 560
+kbytes of it.  Similarly, the decompressor will allocate 3700\ k but only
+touch 100\ k + 20000 * 4 = 180 kbytes.
 
 Here is a table which summarises the maximum memory usage for different
 block sizes.  Also recorded is the total compressed size for 14 files of
@@ -337,7 +335,7 @@ larger files, since the Corpus is dominated by smaller files.
 
 .SH RECOVERING DATA FROM DAMAGED FILES
 .I bzip2
-compresses files in blocks, usually 900kbytes long.  Each
+compresses files in blocks, usually 900\ kbytes long.  Each
 block is handled independently.  If a media or transmission error causes
 a multi-block .bz2
 file to become damaged, it may be possible to
@@ -350,36 +348,36 @@ damaged blocks can be distinguished from undamaged ones.
 
 .I bzip2recover
 is a simple program whose purpose is to search for
-blocks in .bz2 files, and write each block out into its own .bz2 
+blocks in .bz2 files, and write each block out into its own .bz2
 file.  You can then use
-.I bzip2 
+.I bzip2
 \-t
 to test the
 integrity of the resulting files, and decompress those which are
 undamaged.
 
 .I bzip2recover
-takes a single argument, the name of the damaged file, 
+takes a single argument, the name of the damaged file,
 and writes a number of files "rec00001file.bz2",
-"rec00002file.bz2", etc, containing the  extracted  blocks.
-The  output  filenames  are  designed  so  that the use of
-wildcards in subsequent processing -- for example,  
-"bzip2 -dc  rec*file.bz2 > recovered_data" -- processes the files in
+"rec00002file.bz2", etc., containing the  extracted  blocks.
+The output filenames are designed so that the use of
+wildcards in subsequent processing -- for example,
+"bzip2 -dc rec*file.bz2 > recovered_data" -- processes the files in
 the correct order.
 
 .I bzip2recover
 should be of most use dealing with large .bz2
-files,  as  these will contain many blocks.  It is clearly
-futile to use it on damaged single-block  files,  since  a
-damaged  block  cannot  be recovered.  If you wish to minimise 
-any potential data loss through media  or  transmission errors, 
+files, as these will contain many blocks.  It is clearly
+futile to use it on damaged single-block files, since a
+damaged block cannot be recovered.  If you wish to minimise
+any potential data loss through media or transmission errors,
 you might consider compressing with a smaller
 block size.
 
 .SH PERFORMANCE NOTES
 The sorting phase of compression gathers together similar strings in the
 file.  Because of this, files containing very long runs of repeated
-symbols, like "aabaabaabaab ..."  (repeated several hundred times) may
+symbols, like "aabaabaabaab ...\&" (repeated several hundred times) may
 compress more slowly than normal.  Versions 0.9.5 and above fare much
 better than previous versions in this respect.  The ratio between
 worst-case and average-case compression time is in the region of 10:1.
@@ -395,7 +393,7 @@ that performance, both for compressing and decompressing, is largely
 determined by the speed at which your machine can service cache misses.
 Because of this, small changes to the code to reduce the miss rate have
 been observed to give disproportionately large performance improvements.
-I imagine 
+I imagine
 .I bzip2
 will perform best on machines with very large caches.
 
@@ -406,7 +404,7 @@ tries hard to detect I/O errors and exit cleanly, but the details of
 what the problem is sometimes seem rather misleading.
 
 This manual page pertains to version 1.0.8 of
-.I bzip2.  
+.I bzip2.
 Compressed data created by this version is entirely forwards and
 backwards compatible with the previous public releases, versions
 0.1pl2, 0.9.0, 0.9.5, 1.0.0, 1.0.1, 1.0.2 and above, but with the following
@@ -440,13 +438,13 @@ Fenwick (for the structured coding model in the original
 .I bzip,
 and many refinements), and Alistair Moffat, Radford Neal and Ian Witten
 (for the arithmetic coder in the original
-.I bzip).  
+.I bzip).
 I am much
 indebted for their help, support and advice.  See the manual in the
 source distribution for pointers to sources of documentation.  Christian
 von Roques encouraged me to look for faster sorting algorithms, so as to
 speed up compression.  Bela Lubkin encouraged me to improve the
-worst-case compression performance.  
+worst-case compression performance.
 Donna Robinson XMLised the documentation.
 The bz* scripts are derived from those of GNU gzip.
 Many people sent patches, helped
-- 
2.20.1

  parent reply	other threads:[~2019-07-21 20:55 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-01-01  0:00 Some bzip2 manual page patches from Debian Mark Wielaard
2019-01-01  0:00 ` [PATCH 2/3] Mention the --help command line option in the documentation Mark Wielaard
2019-01-01  0:00 ` [PATCH 3/3] Add generation of bzip2.txt and bzip2.1.preformatted to Makefile Mark Wielaard
2019-01-01  0:00 ` Mark Wielaard [this message]
2019-01-01  0:00 ` Some bzip2 manual page patches from Debian Santiago Ruano Rincón
2019-01-01  0:00   ` Mark Wielaard

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190721205419.2904-2-mark@klomp.org \
    --to=mark@klomp.org \
    --cc=anibal@debian.org \
    --cc=bzip2-devel@sourceware.org \
    --cc=foka@debian.org \
    --cc=santiago@debian.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).