%doc package policy

[Warren Togami]

Toshio wrote:
> On Sun, 2005-05-22 at 19:32 -0400, Owen Taylor wrote:
> 
>>On Sun, 2005-05-22 at 12:40 -1000, Warren Togami wrote:
>>
>>>By FC5, we should make it so nothing in our software relies on the 
>>>existence of %doc installed files, that is stuff that ends up in 
>>>/usr/share/doc/%{name}-%{version}-%{release}.
>>>
>>>rpm --excludedocs should create an installed system that works exactly 
>>>the same during runtime.  This is already the case for 99.99% of our 
>>>packages, so complying with this rule would require very few changes.
>>>
>>>Can we come to agreement on this and add this to packaging policy?
>>
>>What does "rely on" mean here? The "Help" menu command in fontforge
>>accesses HTML files that are in the %doc directory. I think it actually
>>falls back to the web if it doesn't find the files, but say it 
>>didn't and displayed an error? Is that relying on the %doc files?
>>
> 
> I know of at least one other packsge that does this.  I think this is
> relying on the %doc file and would have to change under this policy.
> 
> There has also been the occasional tendency to punt on deciding whether
> optional/example programs, init scripts, etc are useful enough to be in
> the package by putting them in %doc.  I think under this policy we need
> to be more careful about doing this.
> 
> Neither of these is a reason not to implement this policy.
> 
> -Toshio

Note that not everything under /usr/share/doc is %doc.  This rule is 
only talking about stuff marked as %doc, not stuff under %files. 
/usr/share/doc can contain stuff listed in %files which is not excluded 
by rpm --excludedocs, I believe all the docs in /usr/share/doc/HTML/ are 
listed under %files instead of %doc.   %doc should be for truly optional 
stuff that is not needed during runtime.

IMHO marking online documentation as %doc isn't great, because it puts 
it into a versioned directory.  Versioned directory handling means more 
complexity when they must be referenced by applications.

https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=155425
This is an example that would be disallowed under this rule.  The RPM 
gpg keys are clearly not documentation.  It is currently included in the 
package as "%doc R*".

Warren Togami
wtogami at redhat.com