* Re: [gentoo-dev] *-doc vs USE="doc"
2003-07-12 8:42 [gentoo-dev] *-doc vs USE="doc" Alastair Tse
@ 2003-07-12 10:25 ` Spider
2003-07-12 14:49 ` Alastair Tse
2003-07-12 11:53 ` Mamoru KOMACHI
1 sibling, 1 reply; 5+ messages in thread
From: Spider @ 2003-07-12 10:25 UTC (permalink / raw
To: gentoo-dev
[-- Attachment #1: Type: text/plain, Size: 3418 bytes --]
begin quote
On 12 Jul 2003 09:42:39 +0100
Alastair Tse <liquidx@gentoo.org> 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
[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [gentoo-dev] *-doc vs USE="doc"
2003-07-12 8:42 [gentoo-dev] *-doc vs USE="doc" Alastair Tse
2003-07-12 10:25 ` Spider
@ 2003-07-12 11:53 ` Mamoru KOMACHI
1 sibling, 0 replies; 5+ messages in thread
From: Mamoru KOMACHI @ 2003-07-12 11:53 UTC (permalink / raw
To: gentoo-dev
Hi,
At 12 Jul 2003 09:42:39 +0100,
Alastair Tse wrote:
> 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.
I agree. It would be better to turn on/off doc installation with "doc"
USE flag (even though it is a user documentation, some may not want to
install any documentation at all).
Also I suggest that we would better have "man" USE flag to decide
whether we will install man pages or not (defaults to turn on).
However, this "man" USE flag raises one question -- how should we deal
with i18n man pages? I've almost translated portage man into Japanese,
but don't know where to ask. I think there are three options:
1. put it into app-i18n/manpages-ja, together with other Japanese
man pages
2. create app-i18n/gentoo-manpages-ja and put portage (and possibly
gentoolkit) man pages into it
3. put it into sys-apps/portage and create <lang> USE flag to
determine which man pages to install
The problem in the first option is that if we install manpages-<lang>,
we have to install all the man pages in it regardless of what
applications we use (eg. we have to install NIS/NFS man pages even when
we don't install them). Currently German, Spanish, French and Russian
have their own man pages in app-i18n, but none of them has portage
man pages translated.
And if we take the second option (originally nakano suggested me this
option) we will have both manpages-ja and gentoo-manpages-ja, which,
in my point of view, does not look nice. However, if we separate
gentoo-manpages-<lang> from manpages-<lang>, we can keep
gentoo-manpages-<lang> up to date pretty easily.
Lastly, if we are to have <lang> USE flag and "man" USE flag, we
should modify /usr/lib/portage/bin/*man to handle i18nised man pages.
If we have USE="ja man", Japanese man pages will be installed in
addition to standard man pages. I think this is the most "gentooish" way
of dealing with i18n, but the problem is we need to split
manpages-<lang> into individual ebuilds. Of course it takes a lot of
time and efforts, and it will get complicated to manage i18n man pages
(though we needn't care about it in each ebuild, as it is hidden in
portage helper scripts shown above). Suppose there is an update of
translated man pages but no change in original source, should we change
the revision number so that people who turn the USE flag on can get
the benefit of it (the most non-<lang> speaker will not get any
advantage from it but be forced to recompile it) ?
Any comments?
regards,
--
Mamoru KOMACHI <usata@gentoo.org>
--
gentoo-dev@gentoo.org mailing list
^ permalink raw reply [flat|nested] 5+ messages in thread