On Sat, Aug 21, 2004 at 08:52:24PM -0400, Michael Sterrett -Mr. Bones.- wrote:

> The "doc" USE flag isn't for installing basic docs for a package -
> those should already be part of a normal merge.  The doc use flag is for
> installing "extra" documentaion of any kind.  Making the installation of
> examples dependent on the "doc" use flag is perfectly fine.  I don't see
> that adding an extra use flag specifically for examples as a good idea.

In java, we have many libraries that are a few hundred kb, that come with
multiple megabytes of generated documentation, that you will only need if
you're a Java developer, and usually not even then.

Also, as javadoc is a memory hog, generating the documentation may be
prohibitive on older machines.

For this reason, we have opted for not installing API documentation by
default.


In addition, some packages come with even bigger examples, that, as I pointed
out, may be full-fledged applications on their own. Even only a small
percentage of Java developers would every want to bother about that, but they
may very well want to have the API docs.

Hence, we have a very real need to separate between docs and examples.


Even though 'examples' may never turn up as a global USE flag, I'm pretty
confident that we'll add it to a good many packages maintained by the Java
herd as a local USE flag in the not-so-distant future.


-- Karl T