FAQ Search Today's Posts Mark Forums Read
» Video Reviews

» Linux Archive

Linux-archive is a website aiming to archive linux email lists and to make them easily accessible for linux users/developers.


» Sponsor

» Partners

» Sponsor

Go Back   Linux Archive > Gentoo > Gentoo Development

 
 
LinkBack Thread Tools
 
Old 12-19-2011, 03:23 AM
Ulrich Mueller
 
Default RFC: deprecate /usr/share/doc/$PF

>>>>> On Sun, 18 Dec 2011, Alexandre Rostovtsev wrote:

>> Can we please avoid the bloat of another directory level here?
>> ${CATEGORY}/${PN} will be even longer than ${PF} in most cases.

> The problem is that ($PN, $CATEGORY) pairs are not unique. Think of
> x11-terms/terminal:0 and gnustep-apps/terminal:0, or
> app-misc/beagle:0 and sci-libs/beagle:0, or app-misc/nut:0 and
> sys-power/nut:0. I could not think of any better solution than using
> $CATEGORY/$PN-$SLOT.

Thinking about it a little more, I believe that ${CATEGORY} shouldn't
appear anywhere in the path of installed files, for the following
reasons:

1. Users may not know the category of a package, therefore it's not
obvious for them where to find its documentation. (Think of it from
the perspective of a user on a multiuser system, who didn't install
the packages on that system.) OTOH, the name of the package (PN) is
obvious in most cases, since it will coincide with the upstream
name.

2. It doesn't play well with bash completion. When searching for
documentation of a specific package (and only knowing PN), one can
currently type the pathname up to PN and press tab which will
complete PVR. With CATEGORY _before_ PN this would no longer work.

3. CATEGORY and SLOT are Gentoo specific, related to the way how we
organise our packages. Neither of them should appear in the
directory structure of installed packages. The problems related to
package and slot moves (where CATEGORY or SLOT change) also show
that something is wrong with the approach. (BTW, in the current
system, PR is also Gentoo specific. It doesn't suffer from problems
with package moves though.)

> Do you have a better proposal that does not rely on $PVR?

Leave things as they are. It's not perfect, but IMHO your approach
would create at least as many problems as it would solve.
Alternatively, a minimal solution would be to drop only ${PR}, i.e.
install documentation under /usr/share/doc/${P}.

Ulrich
 
Old 12-19-2011, 03:48 AM
Dale
 
Default RFC: deprecate /usr/share/doc/$PF

Ulrich Mueller wrote:

On Sun, 18 Dec 2011, Alexandre Rostovtsev wrote:

Can we please avoid the bloat of another directory level here?
${CATEGORY}/${PN} will be even longer than ${PF} in most cases.

The problem is that ($PN, $CATEGORY) pairs are not unique. Think of
x11-terms/terminal:0 and gnustep-apps/terminal:0, or
app-misc/beagle:0 and sci-libs/beagle:0, or app-misc/nut:0 and
sys-power/nut:0. I could not think of any better solution than using
$CATEGORY/$PN-$SLOT.

Thinking about it a little more, I believe that ${CATEGORY} shouldn't
appear anywhere in the path of installed files, for the following
reasons:

1. Users may not know the category of a package, therefore it's not
obvious for them where to find its documentation. (Think of it from
the perspective of a user on a multiuser system, who didn't install
the packages on that system.) OTOH, the name of the package (PN) is
obvious in most cases, since it will coincide with the upstream
name.

2. It doesn't play well with bash completion. When searching for
documentation of a specific package (and only knowing PN), one can
currently type the pathname up to PN and press tab which will
complete PVR. With CATEGORY _before_ PN this would no longer work.

3. CATEGORY and SLOT are Gentoo specific, related to the way how we
organise our packages. Neither of them should appear in the
directory structure of installed packages. The problems related to
package and slot moves (where CATEGORY or SLOT change) also show
that something is wrong with the approach. (BTW, in the current
system, PR is also Gentoo specific. It doesn't suffer from problems
with package moves though.)


Do you have a better proposal that does not rely on $PVR?

Leave things as they are. It's not perfect, but IMHO your approach
would create at least as many problems as it would solve.
Alternatively, a minimal solution would be to drop only ${PR}, i.e.
install documentation under /usr/share/doc/${P}.

Ulrich




I like the logic in #1 as a user. What if two packages have the same
name but different categories tho? It is rare but I do run into this
from time to time. I try to emerge something but am informed by emerge
that I have to include the category for emerge to know exactly which
package I want installed.


I do agree that docs are sometimes hard to find. The only way I have
any success is equery files <package name> then see where it put them or
if there is none to find.


Back to my hole.

Dale

:-) :-)

--
I am only responsible for what I said ... Not for what you understood or how you interpreted my words!

Miss the compile output? Hint:
EMERGE_DEFAULT_OPTS="--quiet-build=n"
 
Old 12-19-2011, 04:31 AM
Alexandre Rostovtsev
 
Default RFC: deprecate /usr/share/doc/$PF

On Mon, 2011-12-19 at 03:41 +0100, Jeroen Roovers wrote:
> For completeness, could you post a list of packages that would benefit
> from your proposed changes? It's a little thing called scope.

I cannot provide you the full list; for that I would have to rebuild the
full tree with USE=doc enabled, and I enable it only for a small number
of packages. But I can give you the packages that I have installed on my
system right now that install a nontrivial set of documentation files
in /usr/share/doc/$PF, files that are worth bookmarking and would
benefit from a location that doesn't change on every revision or version
bump:

app-accessibility/espeak
app-backup/dar
app-benchmarks/phoronix-test-suite
app-crypt/gnupg
app-pda/libimobiledevice
app-text/docbook-sgml-utils
app-text/ghostscript-gpl
app-text/htmltidy
app-text/hyperestraier
app-text/jpdftweak
app-text/openjade
app-text/xmlstarlet
dev-db/postgresql-docs
dev-db/qdbm
dev-db/sqlite
dev-haskell/binary
dev-haskell/dataenc
dev-haskell/deepseq
dev-haskell/haddock
dev-haskell/hashed-storage
dev-haskell/haskeline
dev-haskell/hscolour
dev-haskell/hsql
dev-haskell/hsql-mysql
dev-haskell/hsql-postgresql
dev-haskell/html
dev-haskell/http
dev-haskell/mmap
dev-haskell/mtl
dev-haskell/network
dev-haskell/parsec
dev-haskell/regex-base
dev-haskell/regex-compat
dev-haskell/regex-posix
dev-haskell/tar
dev-haskell/terminfo
dev-haskell/text
dev-haskell/utf8-string
dev-haskell/zlib
dev-java/ant-core
dev-java/icedtea
dev-java/java-sdk-docs
dev-java/sun-javamail
dev-lang/ghc
dev-lang/icon
dev-lang/lua
dev-lang/perl
dev-lang/R
dev-libs/boehm-gc
dev-libs/cyrus-sasl
dev-libs/expat
dev-libs/iniparser
dev-libs/libgamin
dev-libs/libofx
dev-libs/libpcre
dev-libs/libxslt
dev-libs/redland
dev-libs/seed
dev-python/django
dev-python/python-docs
dev-python/sqlalchemy
dev-tcltk/blt
dev-util/astyle
dev-util/valgrind
dev-vcs/git
dev-vcs/subversion
games-emulation/zsnes
games-strategy/freeciv
games-strategy/liquidwar
media-gfx/geeqie
media-gfx/gqview
media-gfx/povray
media-libs/allegro
media-libs/exiftool
media-libs/flac
media-libs/freeglut
media-libs/gd
media-libs/ladspa-sdk
media-libs/libao
media-libs/libkate
media-libs/libsamplerate
media-libs/libsdl
media-libs/libsndfile
media-libs/libtheora
media-libs/raptor
media-libs/tiff
media-sound/esound
media-sound/lame
media-sound/twolame
media-video/ogmrip
net-misc/ntp
net-proxy/polipo
sci-mathematics/maxima
sys-apps/dbus
sys-apps/dstat
sys-apps/groff
sys-apps/kbd
sys-apps/portage
sys-devel/clang
sys-devel/llvm
sys-libs/db
sys-libs/pam
sys-libs/slang
sys-process/fcron
x11-drivers/nvidia-drivers
x11-libs/qt-assistant
x11-terms/rxvt
xfce-base/exo
 
Old 12-19-2011, 05:41 AM
Alexandre Rostovtsev
 
Default RFC: deprecate /usr/share/doc/$PF

On Mon, 2011-12-19 at 05:23 +0100, Ulrich Mueller wrote:
> Thinking about it a little more, I believe that ${CATEGORY} shouldn't
> appear anywhere in the path of installed files, for the following
> reasons:
>
> 1. Users may not know the category of a package, therefore it's not
> obvious for them where to find its documentation. (Think of it from
> the perspective of a user on a multiuser system, who didn't install
> the packages on that system.) OTOH, the name of the package (PN) is
> obvious in most cases, since it will coincide with the upstream
> name.
>
> 2. It doesn't play well with bash completion. When searching for
> documentation of a specific package (and only knowing PN), one can
> currently type the pathname up to PN and press tab which will
> complete PVR. With CATEGORY _before_ PN this would no longer work.

I am forced to agree with your points #1 and #2. $CATEGORY/$PN-$SLOT is
optimized for the "bookmark a document and go back to it a week later"
use case, but you are correct that it would work poorly for the "quickly
look up a doc that you had not cared about until now" use case.

Using /usr/share/doc/$PN-$SLOT with exceptions for packages that have
the same ($PN, $SLOT) but different categories would not scale: it turns
out there are >100 of them in the main tree.

Using /usr/share/doc/$P would be worse than the current situation: doc
locations would still shift on minor version bumps, and packages with
multiple slots in the same $P (e.g. webkit-gtk) would collide.

And using $CATEGORY after $PN is simply too ugly to contemplate.

Fortunately, there *is* a neat solution.

Symlinks.

In other words: no change to dodoc/newdoc/dohtml, they will continue to
install documentation in /usr/share/doc/$PF like they do today.

BUT the package manager will automatically create a symlink
from /usr/share/doc/$CATEGORY/$PN (for slot 0) or
from /usr/share/doc/$CATEGORY/$PN-$SLOT (for slot != 0)
to /usr/share/doc/$PF. This would have to be done after the end of
src_install() so that the symlink goes in the VDB.

I think that this change, similarly to the automatic .la file fixing,
could be implemented by portage without waiting for a new EAPI.

> 3. CATEGORY and SLOT are Gentoo specific, related to the way how we
> organise our packages. Neither of them should appear in the
> directory structure of installed packages.

Slot 0 really is Gentoo-specific; that is why I propose to omit it.
Non-zero slots, however, are usually based on some obvious upstream
property, for example on the major version of the package or on the name
of the pkgconfig file.

You are correct that categories are Gentoo-specific and are therefore
not ideal for installed paths. However, for generating a stable path to
documentation files, one that does not shift on version bumps and
revbumps, there doesn't seem to be any alternative.

-Alexandre.
 
Old 12-19-2011, 07:23 AM
Ulrich Mueller
 
Default RFC: deprecate /usr/share/doc/$PF

>>>>> On Mon, 19 Dec 2011, Alexandre Rostovtsev wrote:

> I am forced to agree with your points #1 and #2.

Good. :-)

> $CATEGORY/$PN-$SLOT is optimized for the "bookmark a document and go
> back to it a week later" use case, but you are correct that it would
> work poorly for the "quickly look up a doc that you had not cared
> about until now" use case.

> Using /usr/share/doc/$PN-$SLOT with exceptions for packages that
> have the same ($PN, $SLOT) but different categories would not scale:
> it turns out there are >100 of them in the main tree.

Probably most of them in app-emacs and app-xemacs.

> Using /usr/share/doc/$P would be worse than the current situation:
> doc locations would still shift on minor version bumps, and packages
> with multiple slots in the same $P (e.g. webkit-gtk) would collide.

> And using $CATEGORY after $PN is simply too ugly to contemplate.

I agree.

> Fortunately, there *is* a neat solution.

> Symlinks.

> In other words: no change to dodoc/newdoc/dohtml, they will continue
> to install documentation in /usr/share/doc/$PF like they do today.

> BUT the package manager will automatically create a symlink
> from /usr/share/doc/$CATEGORY/$PN (for slot 0) or
> from /usr/share/doc/$CATEGORY/$PN-$SLOT (for slot != 0)
> to /usr/share/doc/$PF. This would have to be done after the end of
> src_install() so that the symlink goes in the VDB.

Maybe the symlinks should live in a different directory? Otherwise it
could be confusing for packages like gnustep-base or net-dns whose
name is equal to a category name.

Also I think that the slot should better be separated by a character
that cannot occur in a package name, i.e. something other than
hyphen (-), plus sign (+), or underscore (_). What was the problem
with the colon ( again?

> I think that this change, similarly to the automatic .la file
> fixing, could be implemented by portage without waiting for a new
> EAPI.

Not sure about this one. It's not Portage only, but affects all
package managers.

Ulrich
 
Old 12-19-2011, 07:31 AM
Michał Górny
 
Default RFC: deprecate /usr/share/doc/$PF

On Mon, 19 Dec 2011 00:07:45 +0100
Pacho Ramos <pacho@gentoo.org> wrote:

> El dom, 18-12-2011 a las 23:02 +0100, Michał Górny escribió:
> [...]
> > > Q6: Why can't the dodoc/dohtml path be changed before EAPI-5?
> > > A6: Because the path where dodoc and dohtml install files is part
> > > of the PMS. Portage can't just change it on its own. A possible
> > > workaround for current EAPIs is adding new-style dodoc/dohtml
> > > analogues to an eclass.
> >
> > I think some of devs agree we should be allowed to fix past mistakes
> > without waiting another 20 years till the tree is migrated to a new
> > EAPI...
> >
>
> Maybe this situation could be improved if there was a policy forcing
> us to try to use latest EAPI when possible for any package update,
> that way we would move faster to latest eapi and even deprecate older
> eapis easily

Still unlikely. A bunch of old eclasses will force ebuilds to be EAPI 0
or so.

--
Best regards,
Michał Górny
 
Old 12-19-2011, 07:35 AM
Michał Górny
 
Default RFC: deprecate /usr/share/doc/$PF

On Mon, 19 Dec 2011 05:23:08 +0100
Ulrich Mueller <ulm@gentoo.org> wrote:

> 2. It doesn't play well with bash completion. When searching for
> documentation of a specific package (and only knowing PN), one can
> currently type the pathname up to PN and press tab which will
> complete PVR. With CATEGORY _before_ PN this would no longer work.

You could type /usr/share/doc/*/foo and use tab-completion then. Bash
will suggest all categories or even fill it if only one matches.

--
Best regards,
Michał Górny
 
Old 12-19-2011, 08:02 AM
Michał Górny
 
Default RFC: deprecate /usr/share/doc/$PF

On Mon, 19 Dec 2011 01:41:00 -0500
Alexandre Rostovtsev <tetromino@gentoo.org> wrote:

> Using /usr/share/doc/$PN-$SLOT with exceptions for packages that have
> the same ($PN, $SLOT) but different categories would not scale: it
> turns out there are >100 of them in the main tree.

And I hope there will be more. We should seriously start splitting
packages rather than using old Gentoo bloat like IUSE='perl python
foobar foobaz'.

> Fortunately, there *is* a neat solution.
>
> Symlinks.

Symlinks are never neat. In this particular case, they just mean
someone has failed horribly and now is hoping to fix it taking
the path of least resistance.

> > 3. CATEGORY and SLOT are Gentoo specific, related to the way how we
> > organise our packages. Neither of them should appear in the
> > directory structure of installed packages.
>
> You are correct that categories are Gentoo-specific and are therefore
> not ideal for installed paths. However, for generating a stable path
> to documentation files, one that does not shift on version bumps and
> revbumps, there doesn't seem to be any alternative.

To be honest, the whole ${PF} is Gentoo-specific. Package names not
necessarily follow upstream ones; sometimes we need to change versions
as well to match ${PV} semantics or logic. Perl modules are quite
a large case here.

Sometimes packages in different categories collide. Right now, devs
have to be aware not to install colliding docs -- usually through
renaming files. Using category will at least partially fix this.

Shifting is unavoidable. SLOTs can change, categories can change,
package names can change. Of course, all the mentioned cases are much
rarer than PF changing but -- as pointed out before -- these could
change without reinstalling packages.

If we decided to use such names, the most correct approach would be to
have PM handle docmoves as well. But -- on the other hand -- there will
be always some hardwired paths which will be updated only on real
package rebuild...

--
Best regards,
Michał Górny
 
Old 12-19-2011, 08:03 AM
Ciaran McCreesh
 
Default RFC: deprecate /usr/share/doc/$PF

On Mon, 19 Dec 2011 10:02:07 +0100
Michał Górny <mgorny@gentoo.org> wrote:
> Shifting is unavoidable. SLOTs can change, categories can change,
> package names can change.

We should really just abolish updates and handle changes by reinstalls
plus blockers. Updates are a huge pain, they cause all kinds of problems
and anyone who objects to recompiling a few packages a few times a year
is using the wrong distribution.

--
Ciaran McCreesh
 
Old 12-19-2011, 09:08 AM
Stelian Ionescu
 
Default RFC: deprecate /usr/share/doc/$PF

On Mon, 2011-12-19 at 05:23 +0100, Ulrich Mueller wrote:
> >>>>> On Sun, 18 Dec 2011, Alexandre Rostovtsev wrote:
>
> >> Can we please avoid the bloat of another directory level here?
> >> ${CATEGORY}/${PN} will be even longer than ${PF} in most cases.
>
> > The problem is that ($PN, $CATEGORY) pairs are not unique. Think of
> > x11-terms/terminal:0 and gnustep-apps/terminal:0, or
> > app-misc/beagle:0 and sci-libs/beagle:0, or app-misc/nut:0 and
> > sys-power/nut:0. I could not think of any better solution than using
> > $CATEGORY/$PN-$SLOT.
>
> Thinking about it a little more, I believe that ${CATEGORY} shouldn't
> appear anywhere in the path of installed files, for the following
> reasons:
>
> 1. Users may not know the category of a package, therefore it's not
> obvious for them where to find its documentation. (Think of it from
> the perspective of a user on a multiuser system, who didn't install
> the packages on that system.) OTOH, the name of the package (PN) is
> obvious in most cases, since it will coincide with the upstream
> name.

Every other distro includes the category in the package name, for
example Debian puts mod_fastcgi documentation
in /usr/share/doc/libapache2-mod-fastcgi and in practice it's really not
that big of a problem

> 2. It doesn't play well with bash completion. When searching for
> documentation of a specific package (and only knowing PN), one can
> currently type the pathname up to PN and press tab which will
> complete PVR. With CATEGORY _before_ PN this would no longer work.

It's just an ls -d /usr/share/doc/*/$PN, not worth worrying about


--
Stelian Ionescu a.k.a. fe[nl]ix
Quidquid latine dictum sit, altum videtur.
http://common-lisp.net/project/iolib
 

Thread Tools




All times are GMT. The time now is 10:38 PM.

VBulletin, Copyright ©2000 - 2014, Jelsoft Enterprises Ltd.
Content Relevant URLs by vBSEO ©2007, Crawlability, Inc.
Copyright 2007 - 2008, www.linux-archive.org