This is the mail archive of the libc-hacker@sourceware.cygnus.com mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: RFD: Docs in source directories


On Thu, 9 Jul 1998 18:52:14 +0200, ralf@uni-koblenz.de wrote:
>On Thu, Jul 09, 1998 at 11:12:07AM -0400, Zack Weinberg wrote:
>
>> 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?
>
>Sounds good.  I think the documentation subdirectory could just collect
>all the docs from the add-ons and add them to the documentation as
>appendices.  Not shure if we can find a nice way to deal with links
>between different parts of the documentation.
>
>I don't really like the idea of ripping the documentation apart because
>if you write the documentation as one single document, it usually
>tends to be better written.

So you're suggesting to leave the existing docs where they are but support
inserting additional chapters from add-ons?  That should be doable.

zw



Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]