Re: [gentoo-dev] *-doc vs USE="doc"

[Spider]

begin  quote
On 12 Jul 2003 09:42:39 +0100
Alastair Tse <liquidx@g.o> wrote:

> Hi,
>
> I've noticed that there are a couple of *-docs packages[1] in the
> portage tree. These are usually either developer documentation or user
> documentation.
>
> I also note that we have a "doc" useflag with the definition:
>
> doc - Adds extra documentation (API, Javadoc, etc)
>
> So how should we include documentation with packages? There seems to
> be three schools of thoughts:

<snip>
 
> So how do we currently handle including documentation and why?
>
> I believe we should handle documentation installation uniformly
> portage-wide. I would like to see some discussion into how we should
> handle this situation and what exceptions there are.
>
> Also, it seems to me that the "doc" USE flag is too encompassing. It
> is used for both installing user documentation (user guides,
> application user help) and also to install developer documentation
> (APIs, programming tutorials, Javadoc, etc). I think we should have a
> "devdoc" USE flag to differentiate between the two.

Well, this is an no-issue issue, from the beginning doc was used to
differentiate wether to build the (costly, dependencywise and timewise) 
.ps, pdf. html and other versions of documentation from the original
templates, actions which required jade, tetex and a lot of cpupower, or
wether to just install the basic pregenerated documentation.

This too goes for source-included things like gtk-doc (library
documentation)

So, any case that uses "doc" to differentiate manpages or general 


> For instance, as a user, if I want to install help for all my
> applications, I would put "doc" in my USE flags. But this means it
> will pull in developer documentation from supporting libraries which I
> don't know, use or care about. By differentiating between the two,
> then developers can get their documentation nicely installed along
> with their packages, and also users will get less cruft and more
> useful documentation if they have the "doc" USE flag enabled.

Actually, helpfiles -should- be installed for all applications, and
should definitely not be protected by the USE="doc" statement, as to
remove helpfiles or basic package documentation is to cripple a package,
which we should not do to a user. (if they want their packages crippled
they can tell cron to rm -rf /usr/share/doc/* )



To separate devleoper-documentation is a common thing to do, since API's
tend to change less frequently, so for say java 1.2.*  could well use
the documentation from any java-1.2 standard + some errata

I'd suggest marking all packages that separate end-user documentation
with USE="doc" are flawed and should be fixed.  All those who have extra
developer-centric documentation (api, examples and so on) could well
have them separated in RDEPEND="doc? (${PN}-api-documentation )" 


> Any comments?
>
> Cheers,
>
> Alastair
>
> .. [1] Current -docs packages in portage
> app-doc/php-docs
> app-doc/qt-docs
> app-doc/root-docs
> dev-db/firebird-docs
> dev-java/java-sdk.docs
> dev-python/Cheetah-docs
> dev-python/python-docs
> dev-python/wxpython-docs


> gnome-extra/gnome2-user-docs
This isn't separated but an individual package, pulled in by the gnome
metapackage.


//Spider

-- 
begin  .signature
This is a .signature virus! Please copy me into your .signature!
See Microsoft KB Article Q265230 for more information.
end