RFD: Docs in source directories

[Zack Weinberg <zack@rabi.phys.columbia.edu>]

I'm thinking about moving the documentation source files into the
subdirs with the code they document.  The primary reason to make this
change is that it would make sense to distribute documentation for
an add-on such as linuxthreads with the add-on package.  It also makes
it easier to find the documentation for any given chunk of source.

The major hurdle is in preserving the ordering relation between
chapters.  As a first try we can enforce a rule that all top-level
nodes must use explicit @node commands, and then do a topological sort
on the next pointers.  That works as long as all chapters are always
present; but it breaks the moment we allow a chapter to be distributed
in an add-on.  Another option is a file that lists each potential
chapter and the directory it lives in; that would work but means the
core distribution has to be aware of all the possible add-ons (that
want to add to the manual).

What do people think?

zw