Red Hat Bugzilla – Bug 151907
The help file ought to be marked as documentation
Last modified: 2007-11-30 17:11:02 EST
From Bugzilla Helper:
User-Agent: Mozilla/5.0 (X11; U; Linux i686; sv-SE; rv:1.7.3) Gecko/20041020
Description of problem:
I did an "rpm -qd audacity" after installing, and only the manual page and the LICENSE and README files were found. Which didn't tell me that much about how to use the tool. But as it turned out, the documentation IS included, /usr/share/audacity/audacity-1.2-help.htb, but just not marked %doc in the spec file.
Version-Release number of selected component (if applicable):
Steps to Reproduce:
1. rpm -qd audacity
Actual Results: /usr/share/audacity/audacity-1.2-help.htb isn't shown.
The problem is that the help file is used by the program in its internal help
browser. RPM has an option to uninstall documentation, thus in a way breaking
the application. Similarly documentation for gnome apps residing in
/usr/share/gnome/help or /usr/share/omf are not marked as documentation.
Further, the file is compressed html with a non-standard file name extension,
$ file /usr/share/audacity/audacity-1.2-help.htb: Zip archive data, at least
v2.0 to extract
so exposing it to users explicitly as a %doc file, would be the wrong thing to do.
I hadn't realised before, but I guess %doc is used for two different purposes.
1) To declare to the user what documentation a package contains, and 2) to
declare to rpm what files are not needed by the application since they are
"only" documentation not directly referenced.
The purposes are clearly related, but not quite the same. A bit unfortunate.
But I guess not big enough deal to do anything about.
It's 1) only, %doc marks documentation files.
2) is a side-effect. With huge documentation directories (extensive library API
documentation in form of hundreds of HTML files, for instance) comes the desire
to exclude %doc files during installation of packages.
But that is not the point here. Surely one could duplicate this particular doc
file and make it appear also in %_docdir. It's just not useful, rationale given
in comment 2. And Audacity is a graphical application with a Help menu.