I've been trying to build a new system, with the most recent Stage 3 and
portage snapshots, and found that I can no longer emerge anything with
the doc flag set. There have always been a couple of blocks with the
doc flag set, but I can make adjustments for those in package.use.
Now there are a couple of hundred lines of blocks, and no apparent way
to find out where the problem starts.

It's a couple of months since I last installed Gentoo, so I may be out of
touch, but is the doc flag still thought to be usable at all?

USE="doc" and USE="debug" are kind of special flags that you should enable only per package in package.use, instead of make.conf. I know it's not well documented issue,
but that's just how it's always been.

USE="doc" and USE="debug" are kind of special flags that you should enable only per package in package.use, instead of make.conf. I know it's not well documented issue,
but that's just how it's always been.

Well, that's the first I've heard of it; and a Gentoo system without documentation isn't a very useful system.
And if I add the doc flag in package.use I get exactly the same failure anyway.

From early 2005 to early 2009 you could emerge a Gentoo system with "doc" in make.conf and two or three
packages masked out with "-doc" in package.use. It now looks as if several packages have been added to the
"invalid doc flag" list, as well as a couple of other flags. I've been trying to emerge a Gentoo system based on
the 20091006 portage snapshot and stage 3 file, with the USE flags doc, X, and gnome (among others) set in
make.conf. Generally I try to minimise the flags in make.conf, but those three seem widely enough used to
be global settings. After a lot of messing about, I ended up with the following flags in package.use:

There are probably other sets of packages that would have the same effect, but that's the
first that I found. I can't find any reason or method in the list; perhaps you can.

There are still broken system packages, of course - sys-libs/db-4.7.25_p4 won't emerge, due
to some sort of patch mixup, and portage blows up if you give it the doc flag, but once the flags
above are set stuff mostly works.

You can definitely add dev-lang/ruby to the list.
Last time I tried emerging ruby with USE=doc my box nearly went berserk.

That's worth knowing, but I was just checking the stuff that really ought to work,
"emerge system", "emerge xorg-x11" (since most people use it), and possibly
"emerge gnome". Outside that list (and kde, of course) the individual use of
package flags can vary quite widely, so you really have to try it and see what
happens.

Well, that's the first I've heard of it; and a Gentoo system without documentation isn't a very useful system.
And if I add the doc flag in package.use I get exactly the same failure anyway.
Will

Oh, default docs are always installed (such as README, ChangeLog and so forth). USE "doc" usually controls internal API docs, useful if you are doing development with the certain package... and similar.

Never heard that before
1.) as ssuominen pointed out already, READMEs and so on are installed anyhow, regardless of the doc flag being set or not. Just have a look into /usr/share/doc.
The same is true for man pages—you don't need the doc flag for that.
2.) doc installs additional documentations—just read the relevant USE description:

3.) I definitely would set the doc flag on a per package basis; in my case, this is only for php and apache
4.) Still, if you do not set it for any package, it's all on the internet—we're in the open source world
5.) just one additional remark: if you want to install the user docs for kde, you need the handbook use flag_________________Mandrake Dec 2001 · Debian "Woody" Aug 2002 · Gentoo Jan 2004 · Funtoo Oct 2009

If I'm going to have to download the documentation (and it's usually included
in the Gentoo packages) then it seems reasonable to make it available. One
of Gentoos main advantages is access to the source code of packages, and
documentation is equally useful. README's are generally short and irrelevant,
where they exist at all.

Until recently there were only three blockers that prevented the use of the doc
flag; now there are four more, and I'm not even sure that you can run
"emerge system" successfully with a global X flag set. (I went round and round
with "X" and "doc", and I don't know exactly where I ended up.) It seems a
point worth noting, especially since new-comers to Gentoo may want to start
by reading the docs. On present form, such an approach would be ill-advised.

If I'm going to have to download the documentation (and it's usually included in the Gentoo packages) then it seems reasonable to make it available. One of Gentoos main advantages is access to the source code of packages, and documentation is equally useful. README's are generally short and irrelevant, where they exist at all.

I actually agree with you, which is why I took the trouble to learn how to solve the blocks. (I believe you and I have corresponded on this topic before.) I wanted to let you know that I have several full Gentoo systems with the doc USE flag globally enabled. Yes, there were blocks (caused by circular dependencies) initially but they have always been pretty easy to solve. After initial solution, periodic updates run smoothly with no additional (documentation induced circular dependency) blocks. And, yes, I have X installed (and KDE, too). I don't think I've ever spent more than ten or fifteen minutes solving those circular dependencies. The basic technique is as follows:

Build the system up to the point that it's self supporting and up to date with the doc USE flag off.

and, if there are circular dependencies, note the application at the deepest indented level of the dependency tree (which should be right where the circular dependency turns back on itself).

Build that package without the doc USE flag (be sure to use --oneshot; it's just a dependency, after all):

Code:

USE="-doc" emerge -1v some_package

This will also build (at least) the first package in the circle without the doc USE flag. You may also need to build others; there is sometimes a little trial & error involved. Same technique, though.

Repeat the previous two steps as necessary until the circle is broken.

Run the first example emerge again without --pretend to actually build all those packages with documentation.
The dependencies of the documentation build tools are vast, complex, and sometimes circular. I have a hard time blaming Portage for that. Nevertheless, Portage's heuristics for solving blocks on its own have improved over the last year or two and I expect that it will eventually incorporate more sophisticated heuristics that'll automatically deal with doc USE flag induced circular dependency blocks as well.

Bottom line: this is a minor annoyance, not a big deal.

- John_________________I can confirm that I have received between 0 and 499 National Security Letters.

It used to be a minor annoyance; for some reason, this time it turned bloodstained
on me. In fact, I cleared off the filesystem and reloaded the portage snapshot
and stage 3 to check what I'd found, and the only new packages that need
suppressing for "USE=doc emerge system" are in fact libxcb and fontconfig.
Still, after four years with no change, I find that surprising.

Certainly there's nothing wrong with the ebuilds individually; it's when they are
put together that the problems start. I built some dependency graphs for the
main packages I use, and some of them are real rats nests. However, I don't
think that's something that's checked in a build, so it has to be accepted.