Grant <virus@clear.net.nz> wrote:
> I've emerged xman.
> The program dialogue box runs ok but the man page output is full of
> garbage
>
> This is a small part of the dump after prog terminated :
> eqn:/usr/share/man/man1/man.1.bz2:23: invalid input character code `0'

The .bz2 extension tells it all. bzip2 is not a universal compression
format, and whoever in Gentoo thought it was a good idea to compress man
pages with it should have his danglies compressed with bzip2.
In your case, xman doesn't understand the bzip2 format, which it shouldn't
be expected to understand either, cause it's non-standard.

The traditional way to pack man files in Unix is with "pack"[1], which has
the advantage that even though it doesn't pack all that well, unpacking
takes extremely little CPU, and is generally faster than a cat of the same
file. That's why the files were compressed in the first place -- to save
/time/, not to save disk space. And why bzip is such a horrible choice; on
a slow or CPU-pegged system, it takes longer to uncompress a .bzip file than
to read a much bigger file from disk, and while doing this, you'll use 100%
CPU on a core, slowing down the entire system.

As a better alternative to bzip2, there's three real alternatives:

1: Use gzip instead. This used to be the default for Gentoo, until some
ignorant asshat changed it. The downside to using gzip is if man pages are
shared with a non-Linux system where gzip hasn't been installed, then man
pages won't work on that system.
To use gzip, add the following two lines to /etc/make.conf:
PORTAGE_COMPRESS="gzip"
PORTAGE_COMPRESS_FLAGS="-8" # Or -7. Using -9 is silly, it just eats CPU
Then edit /etc/man.conf, and change the following two lines:
COMPRESS /bin/gzip
COMPRESS_EXT .gz

2: Use compress instead. This is present on /all/ Unix like systems I can
think of, except Gentoo, unless it has been installed specifically. (Again,
some strange choices by the newer devs.) The advantage is that if you share
some man pages over NFS to other systems, they won't have a problem.
To use compress, "emerge ncompress", then add the following two lines to
/etc/make.conf:
PORTAGE_COMPRESS="compress"
PORTAGE_COMPRESS_FLAGS=" " # Due to a bug in some versions of portage
Then edit /etc/man.conf, and change the following two lines:
COMPRESS /usr/bin/compress
COMPRESS_EXT .Z

3: Keep man pages uncompressed. The saving for compressing man pages is
minimal, because the man pages themselves are so small. Unless enough space
is saved by compressing to reduce the number of disk blocks, there's no
saving at all, just increased CPU usage. As an example, if your file system
has a 4 kB block size, and compressing reduces the size from 7900 to 4200
bytes, you save exactly *zero* disk space. And, remember, the purpose of
compressing in the first place was to save /time/ and CPU use, not space[2].
This is what I'd recommend.
To not use compressed man pages, except for catman pages, add the following
two lines to /etc/make.conf:
PORTAGE_COMPRESS=""
PORTAGE_COMPRESS_FLAGS=" " # Due to a bug in some versions of portage
Then edit /etc/man.conf, and change the following two lines:
COMPRESS /bin/gzip
COMPRESS_EXT .gz

Approach #3 above will also have the side effect that files under
/usr/share/doc will not be compressed, which is nice. It's especially nice
for the doc files that come in html format, with one doc linking another.
(If using compression, you would have to uncompress all the files, and then
recompressing them afterwards, else portage would not find the original
files when updating a package, possibly leaving you with both compressed and
uncompressed files in the same directory.)

After doing one of the above, you have to re-emerge any packages that puts
files in /usr/share/man or /usr/share/doc. Easiest is to "emerge -e world"
before going to bed.

And then go to http://bugs.gentoo.org/show_bug.cgi?id=169260 and voice your
opinion.

[1]: "pack" compressed files have a .z (lower case) extension, not to be
confused with the .Z (upper case) extension which "compress" uses.
Unfortunately, "pack" isn't even available for Gentoo!
[2]: That's why "catman" saves a compressed version of the formatted man
page when you read it for the first time, and then does a zcat on that
instead of reformatting every time you re-read a man page. You burn disk
space that way, but save CPU time.

Regards,
--
*Art