I updated sys-apps/groff from 1.21 to 1.22.2. The newer groff package includes two new commands not present in the older release, gropdf and pdfmom. These two executables were correctly installed in /usr/bin. However, their associated man pages were not installed. All other groff man pages were correctly upgraded to the 1.22.2 versions. Discussion on the groff email list points to this being problem with the Gentoo groff package, and not the groff code base: http://lists.gnu.org/archive/html/groff/2014-07/msg00005.html http://lists.gnu.org/archive/html/groff/2014-07/msg00006.html
Bug 487276 comment 8 explains how this bug was introduced, and how it can be fixed.
Another groff-1.22.2 documentation bug is that the groff_mom man page indicates that the PDF manual can be found at /usr/share/doc/groff-1.22.2/pdf/mom-pdf.pdf. However, this file is also missing. According to the groff-1.22.2.ebuild script, this file is only installed if the "examples" USE flag is set. But since this PDF file is a manual, not examples, it's not appropriate to include or exclude it based on whether "examples" is set. This can be fixed very simply by removing from groff-1.22.2.ebuild the line that refers to mom-pdf.pdf.
And still one more bug: Even when USE=examples is set and all examples are thus installed, the pointer to them in the groff_mom man page is incorrect. This man page points to /usr/share/doc/groff-1.22.2/examples/mom/*.mom. This path has no matches because the files on the system are compressed: they are installed at /usr/share/doc/groff-1.22.2/examples/mom/*.mom.bz2 It does not make sense to compress these files. Unlike man pages or other files one typically views via "man" or "less," which can uncompress on the fly, these example files are meant to be processed by groff, which does not automatically uncompress input files. So making use of these examples requires intermediate files or a more convoluted command line. Also, the space saved by compressing the files amounts to 49,519 bytes: a minuscule amount in, say, 1994, when hard drive sizes were measured in megabytes; an utterly unnoticeable amount in 2014. Anyone on a system where 48K of disk space matters won't install the examples anyway. Therefore, I believe the correct fix is to install the files uncompressed on the system, rather than changing the groff_mom man page to point to the compressed path. But one of these must be done to make the man page reference correct.
Also as in comment #3, the man page for pic(1) includes pointers to /usr/share/doc/groff-1.22.2/pic.ms and /usr/share/doc/groff-1.22.2/pic.ps, neither of which exists because the respective files were compressed on installation.
Could you have a go at patching the ebuild to do as you suggest, and attach it here as a unified diff please?
(In reply to Tony Vroon from comment #5) > Could you have a go at patching the ebuild to do as you suggest, and attach > it here as a unified diff please? I will look into the problems described in comment #0 and comment #2. I believe the proper fix for the problems described in comment #3 and comment #4 is to change the default value of PORTAGE_COMPRESS_EXCLUDE_SUFFIXES, amending it to include the suffixes "mom ms ps". "mom" and "ms" are unlikely to be used by any packages besides groff, so their addition will solve the aforementioned bugs without side effect. Other packages might have PostScript documentation files, and so might be affected by adding "ps" to PORTAGE_COMPRESS_EXCLUDE_SUFFIXES. However, since "pdf" is already included in the list, "ps" ought to be anyway. These two file formats have essentially the same purpose; it makes little sense for one to be included and one exlcuded. Do you agree with this reasoning?
fix is in groff-1.22.3 which is in the tree
(In reply to SpanKY from comment #7) > fix is in groff-1.22.3 which is in the tree There are four bugs listed in this bug report, respectively described in comment #0 comment #2 comment #3 comment #4 It is clear at a glance into groff-1.22.3.ebuild that the bug described in comment #2 is not fixed in groff-1.22.3. I cannot yet say about the others.
(In reply to Dave Kemper from comment #8) this is exactly why we have the "one bug report per bug report" rule. the summary talks about man pages and that's fixed. please stick to this rule. otherwise this turns into a complete mess. i've updated the ebuild to not delete the pdf: http://sources.gentoo.org/sys-apps/groff/groff-1.22.3.ebuild?r1=1.1&r2=1.2 wrt doc paths and compressed files, i'm going to punt on that. people aren't stupid and can figure out how that works. wrt the examples being compressed, i think it's fine. people can figure out how to decompress something before messing around with things.
> this is exactly why we have the "one bug report per bug report" rule. Apologies. I was unaware of this rule, and thought the various bugs were closely related enough to be grouped together. > i've updated the ebuild to not delete the pdf: > http://sources.gentoo.org/sys-apps/groff/groff-1.22.3.ebuild?r1=1.1&r2=1.2 Thank you! > wrt doc paths and compressed files, i'm going to punt on that. people > aren't stupid This is not universally true. ;-) > and can figure out how that works. The basic purpose of documentation is to help the user figure out the software. If the user has to "figure out" incorrect documentation in the process, the documentation is working at cross purposes. Yes, in this case the impediment is slight, but it breaks simple things -- like cutting and pasting or hyperlinking to a pathname -- that ought to Just Work. And, foremost, fixing the problem is so trivially simple that it's hard to conceive of a good reason for refusing to do so. Documentation should be correct; I'm not sure why that's at all controversial. But your point above is taken, so I'll open a new bug report for this. > wrt the examples being compressed, i think it's fine. people can figure out > how to decompress something before messing around with things. If they remain compressed, that's fine (though less optimal, I believe), as long as the pointers to them in the man pages are corrected.
