Packaging guidelines for documentation clairfication needed

[Ralf Corsepius]

On 09/14/2015 04:13 PM, Richard Shaw wrote:
> While working through a package review[1] this excerpt from the
> documentation section[2] was brought to my attention:
>
> "Marking a /relative/ path with |%doc| in the |%files| section will
> cause RPM to copy the referenced file or directory from |%_builddir| to
> the proper location for documentation. Files can also be placed in
> |%_pkgdocdir|, and the build scripts of the software being packaged may
> do this automatically when called in |%install|. However, mixing these
> methods is problematic and may result in duplicated or conflicting
> files, so use of |%doc| with /relative/ paths and installation of files
> directly into |%_pkgdocdir| in the same source package is forbidden."
>
> In my case the project is installing html documentation during "make
> install". Reading this pedantically, it would appear that would prevent
> me from using %doc to install the obligatory COPYING, README, ChangeLog,
> NEWS, etc...
>
> This doesn't seem to be very practical and I'm not sure that's what was
> intended by the guidelines.

Older versions of rpm allowed mixing relative %doc and direct installs 
into %_pkgdocdir.

rpm - as upstream calls it - "fixed it" (IMHO, they broke rpm - of 
course upstreams disagrees with me).

As a consequence of this, rpm now often errors out, when mixing  both 
styles. The only reliable way, now seems to be to either manually 
install everything to %_pkgdocdir directly or only use relative %doc.

ATM, I am recommending against using relative %doc and recommend to 
directly install docs into %_pkgdocdir.

You typically end up with something similar to:

%install
make install DESTDIR=${RPM_BUILD_ROOT}

install ... COPYING README ... ${RPM_BUILD_ROOT}%{_pkgdocdir}

%files
%{_pkgdocdir}
...


Ralf