USEing "doc"

zolxd · Tux's lil' helper Joined: 14 Feb 2003 Posts: 92

When I began using Gentoo, I thought that "doc" would be very useful, and put it in make.conf.
"Documentation" is a fairly broad term, and the use.desc didn't refine it much.

What I found of course, was a folder for every item, containing gz'd text files, that only root could unpack (by default), and providing no information helpful to the user.
Typically, README*, CHANGELOG, MANIFEST, AUTHORS, LICENSE sort of thing.
(* a sure sign that there is no content)

I also found that sometimes user documentation was smuggled in, too.

Eventually, I removed "doc" from USE, and only collected documentation on demand, by searching for it elsewhere.

Today, I decided to empty /usr/share/doc completely. I keep what I use in a separate directory where it's less cluttered anyway.

Do you enable "doc", and if so, why?

What seems useful to me is a distinction between types of documentation.

doc - user documentation, if provided.
devnotes - details/acknowledgements useful to hackers/contributors of that item.
legal - licenses and which software uses what.

Comments?
_________________
core i7 + ati 5400 on GA-P55

yabbadabbadont · Posted: Wed Nov 08, 2006 11:16 pm Post subject:

Well, as long as it is left up to the individual ebuild writers to decide what the doc USE flag means, I think this is pretty much what we will see.

I like your idea though.

_________________

Hagar · Guru Joined: 11 Feb 2003 Posts: 445

Not all files in /usr/share/doc are controlled by the doc useflag. (read: most aren't)

Unpacking them has nothing to do with being root.
Unpacking them inside /usr/share/doc however does, because only root has write permissions in that directory.

And though not all files might be useful to you, they are to others, and some are just required (license, author)
Documentation can be defined in many ways, and so far there has been no need to define this in portage.

* Hagar waves at yabba again

numerodix · l33t Joined: 18 Jul 2002 Posts: 743 Location: nl.eu

If I'm looking for documentation for something, I go online. I basically never use docs, except for man pages for commonly used apps. I figured I could save some space by not installing docs and so I have -doc in my USE. I really haven't come to regret it, in the few cases I needed the docs I set doc per package (2 or 3 times).

Btw you can read text files gzipped with less for instance, unzipping on the fly and no special permissions needed.
_________________
undvd - ripping dvds should be as simple as unzip

timeBandit · Posted: Thu Nov 09, 2006 1:32 am Post subject:

I also enable doc on a per-package basis, because as noted its effect varies widely. F'rinstance ImageMagick used to install a reference guide without the flag, then one day (read: one update) it disappeared. So it earned a doc flag. Silly ebuild, suddenly becoming sensible.

_________________
Plants are pithy, brooks tend to babble--I'm content to lie between them.
Super-short f.g.o checklist: Search first, strip comments, mark solved, help others.

zolxd · Tux's lil' helper Joined: 14 Feb 2003 Posts: 92

runningwithscissors · Posted: Thu Nov 09, 2006 2:31 am Post subject:

I use it while downloading some GTK libs and stuff. But the documentation for that is stored at /usr/share/gtk-doc. I just think there ought to be either a proper directory for relevant documentation (yes, that includes library documentation in addition to license and usage information). It would make things a lot easier.

It isn't a major hindrance, but it could be improved.

adekoba · Tux's lil' helper Joined: 06 Oct 2006 Posts: 129

i just look it up on the internetz

mark_alec · Posted: Thu Nov 09, 2006 10:25 am Post subject: Re: USEing "doc"

Dralnu · Veteran Joined: 24 May 2006 Posts: 1919

OT:

Where are the manpages located at? I'm always looking for a good way to trim down my system, and since I don't use the doc useflag, trashing alot of the docs would be nice...
_________________
The day Microsoft makes a product that doesn't suck, is the day they make a vacuum cleaner.

timeBandit · Posted: Tue Nov 28, 2006 12:49 am Post subject:

It depends on your installed packages, but most are in /usr/share/man. echo $MANPATH to see the manual directories in active use, or

zxy · Posted: Wed Nov 29, 2006 4:50 am Post subject:

I have set doc useflag globaly once. I learned a lot.
First I removed the flag, as emerging gtk+ for example took a loooong time, due to installing documentation.
I think installing all docs took more than compiling (gtk+)

If I would really need some documentation then pre-package is the only option. And there is the internet, too.
_________________
Nature does not hurry, yet everything is accomplished.
Lao Tzu