This is the mail archive of the
libc-hacker@sourceware.cygnus.com
mailing list for the glibc project.
Re: RFD: Docs in source directories
- To: ralf@uni-koblenz.de
- Subject: Re: RFD: Docs in source directories
- From: Zack Weinberg <zack@rabi.phys.columbia.edu>
- Date: Thu, 09 Jul 1998 13:02:29 -0400
- cc: libc-hacker@cygnus.com
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