[Fedora-packaging] Doc packaging questions

[John Dennis]

On 07/23/2013 03:33 PM, Ville Skyttä wrote:
> Related to the unversioned docdirs F-20 feature [1], here's a couple of
> questions:
> 
> 1) Should specfiles be using %{_docdir} or %{_defaultdocdir} when
> referring to the /usr/share/doc dir? Both seem to work, both are being
> used. To me %{_docdir} sounds better for some reason.
> 
> 2) Packages that want to refer to the doc dir created by the special
> %doc form need to take %{_docdir_fmt} into account. I didn't find a nice
> way to do it, but here's one uglyish way to define a variable in
> specfiles that should point to the correct location before and after the
> %{_docdir_fmt} change (everything on one row):
> 
> %global pkgdocdir %{_docdir}/%{?_docdir_fmt:%{expand:%(echo
> '%{_docdir_fmt}' | tr A-Z a-z)}}%{!?_docdir_fmt:%{name}-%{version}}

Shouldn't this be in one of the macro files and not replicated in
various spec files?

> 
> Do we want to encourage using this in specfiles that need to refer to
> the dir created by %doc, or does someone have a better solution?

I never liked the magic behavior of %doc. Nothing else magically
installs files by simply applying an attribute, it's weird, under
documented and error prone. Apparently the behavior depends on whether
the filenames which follow the %doc directive are absolute or not, make
a mistake in listing the file and you get different behavior. The %doc
documentation is also incomplete when it comes to sub-package behavior.
In many instances you want the sub-package to install it's doc in the
doc area for the main package.

All of the above is why I explicitly define a docdir macro in my spec
files and explicitly install files relative to it. This eliminates the
under specified magic behavior of %doc and replaces it with well defined
actions. Also a number of configure scripts accept a docdir
configuration option so when make install runs it will install it's
documentation relative to this root directory. Another reason to have a
nicely defined docdir variable.

When I tried to bring my packages into alignment with the proposed
change I discovered it was not obvious at all how to make it work
cleanly because there doesn't seem to be any predfined docdir variable
which implements the before and after behavior (versioned vs. unversioned).

I strongly suggest the standard macros define a pkgdocdir variable, if
it's not defined it can default to the previous behavior. Off the top of
my head I would think a spec file might look like this:

%global docdir %{?pkgdocdir:%{_docdir}/%{name}-%{version}}

> 
> Packages can obviously conditionalize stuff on 0%{?fedora} >= 20 but
> that doesn't sound too nice to me.
> 
> [1] https://fedoraproject.org/wiki/Changes/UnversionedDocdirs
> --
> packaging mailing list
> packaging at lists.fedoraproject.org
> https://admin.fedoraproject.org/mailman/listinfo/packaging
> 


-- 
John