* [gentoo-dev] *-doc vs USE="doc"
@ 2003-07-12 8:42 Alastair Tse
2003-07-12 10:25 ` Spider
2003-07-12 11:53 ` Mamoru KOMACHI
0 siblings, 2 replies; 5+ messages in thread
From: Alastair Tse @ 2003-07-12 8:42 UTC (permalink / raw
To: gentoo-dev
[-- Attachment #1: Type: text/plain, Size: 2373 bytes --]
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:
1. Include the documentation inside the same package protected by the
"doc" USE flag.
2. Separate out the documentation into its own package (eg.
"python-docs") and make the user install the documentation themselves.
3. Separate out the documentation into its own package and make the
parent package RDEPEND or PDEPEND the documentation package using the
"doc" USE flag.
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.
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.
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
--
Alastair 'liquidx' Tse
>> Gentoo Developer
>> http://www.liquidx.net/ | http://dev.gentoo.org/~liquidx/
>> GPG Key : http://dev.gentoo.org/~liquidx/liquidx_gentoo_org.asc
>> FingerPrint : 579A 9B0E 43E8 0E40 EE93 BB1C 38CE 1C7B 3907 14F6
[-- Attachment #2: This is a digitally signed message part --]
[-- 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 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
* Re: [gentoo-dev] *-doc vs USE="doc"
2003-07-12 10:25 ` Spider
@ 2003-07-12 14:49 ` Alastair Tse
2003-07-12 15:22 ` Peter Ruskin
0 siblings, 1 reply; 5+ messages in thread
From: Alastair Tse @ 2003-07-12 14:49 UTC (permalink / raw
To: gentoo-dev
[-- Attachment #1: Type: text/plain, Size: 1758 bytes --]
On Sat, 2003-07-12 at 11:25, Spider wrote:
> 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
>
OK, so "doc" is only to separate developer documentation? Is that a fair
definition? If so then I think the description of the useflag should be
modified. Because right now, it is very vague saying "Add Extra
Documentation".
> 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 )"
That seems reasonable. I just want clarify how we should handle docs. I
guess this is acceptable way. Just wondering why the docs aren't
actually included in the package themselves.
Cheers,
--
Alastair 'liquidx' Tse
>> Gentoo Developer
>> http://www.liquidx.net/ | http://dev.gentoo.org/~liquidx/
>> GPG Key : http://dev.gentoo.org/~liquidx/liquidx_gentoo_org.asc
>> FingerPrint : 579A 9B0E 43E8 0E40 EE93 BB1C 38CE 1C7B 3907 14F6
[-- Attachment #2: This is a digitally signed message part --]
[-- 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 14:49 ` Alastair Tse
@ 2003-07-12 15:22 ` Peter Ruskin
0 siblings, 0 replies; 5+ messages in thread
From: Peter Ruskin @ 2003-07-12 15:22 UTC (permalink / raw
To: gentoo-dev
On Saturday 12 Jul 2003 15:49, Alastair Tse wrote:
> That seems reasonable. I just want clarify how we should handle docs.
> I guess this is acceptable way. Just wondering why the docs aren't
> actually included in the package themselves.
Sometimes the sources are different. Please see Bug #24335 for an
example of API docs and tutorials depending on the doc flag.
Peter
--
==================================================
Gentoo Linux: Gentoo Base System version 1.4.3.8p1
kernel-2.4.22_pre2-gss i686 AMD Athlon(tm) XP 1600+
==================================================
--
gentoo-dev@gentoo.org mailing list
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2003-07-12 15:22 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
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 15:22 ` Peter Ruskin
2003-07-12 11:53 ` Mamoru KOMACHI
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox