[Fedora-packaging] RFE: Documentation packages - no base packagedependency

[Toshio Kuratomi]

On Mon, Jun 10, 2013 at 12:40 AM, Mamoru Tasaka
<mtasaka at fedoraproject.org> wrote:
>
>> https://fedoraproject.org/wiki/Packaging:Guidelines#Documentation
>>
>> Proposed addition to the guidelines:
>>
>>     Independent documentation -doc packages typically don't require the
>>     base package. It should be possible to install documentation without
>>     having to install a program and all its dependencies.
>>
>> Rationale: Recently, in package review requests, I've seen packagers apply
>>  https://fedoraproject.org/wiki/Packaging:Guidelines#Requiring_Base_Package
>> also to -doc packages. And there are packages in the collection, which
>> do that, too. This is a hindrance, especially if one only wants to peruse
>> the documentation or install API documentation for remote developing.
>> Of course, an exception to this is documentation in a special format,
>> which can only be viewed within an application.
>>
>> Thoughts?
>
There's two things I remember from the past:

* We want (need?) license files to be present in either the subpackage
or a Require'd main package.  So the draft should mention that.
* I remember a discussion about this where rationale for including the
Requires was because the API could change and you'd want to make sure
that the documentation that you had installed matched with the API of
the library you have installed.  I think this is a tradeoff and I
personally incline towards your rationale being the stronger one.


I'd like to see the rationale about wanting to browse the
documentation locally for remote developing added to the Draft.  If
you'd be willing to open up an FPC ticket with an updated draft we can
vote on it at the next meeting.

> Additionally, I think that many -doc subpackage requires main package is because
> -doc installs documents under the directory the main package owns:
> i.e. the main package has some "important" documents in one directory
> and the rest documents are included in -doc subpackage, and -doc uses the
> same directory. Usually I don't want to duplicate ownership of the same directory
> for this reason (so usually make -doc subpackage require main package),
> however I don't object to your thought so much. I think it is better to write explicitly
> that duplicating directory ownership is allowed (if your new proposition is
> accepted).
>
This is a further wrinkle.  It may deserve its own section.  To just
use something like:

%files
%doc LICENSE

%files doc
%doc LICENSE API_docs/*

doesn't run afoul of this and seems pretty straightforward to me.

When you want to place the docs in the documentation directory of the
main package, there's other things you have to do besides manage
package ownership.  IIRC, you end up having to manage the
documentation directory explicitly yourself and *cannot* use the %doc
macro.

%install
mkdir -p %{buildroot}%{_docdir}/%{name}%{version}-%{release}
cp -pr README LICENSE api_doc
%{buildroot}%{_docdir}/%{name}%{version}-%{release}/

%files
%{_docdir}/%{name}%{version}-%{release}/
%{_docdir}/%{name}%{version}-%{release}/README
%{_docdir}/%{name}%{version}-%{release}/LICENSE

%files doc
%{_docdir}/%{name}%{version}-%{release}/
%{_docdir}/%{name}%{version}-%{release}/LICENSE
%{_docdir}/%{name}%{version}-%{release}/api_doc

More complex and easy to get wrong (Someone please correct me if this
has changed or I'm flat out wrong.  It's been a while since I played
around with this)

Anyhow, the added complexity is why I think this might deserve its own section.

-Toshio