Re: treelang patch parts n of 6

["Joseph S. Myers" <jsm28 at cam dot ac dot uk>]

On Mon, 6 May 2002, Tim Josling wrote:

> the texi over time (discussed at length in earlier posts). Some of the
> material belongs in the main gcc manual as was pointed out, but it is
> not yet production ready, so it is separate for now. Apart from

It might reasonably be considered that sourcebuild.texi is not yet 
production-ready, being full of FIXMEs.  It's there as a framework for 
people to add to and fix the FIXMEs.  The structure of the gccint manual 
into sections and chapters is far from final.

If you have something to say about any aspect of GCC internals - even if
preliminary and very incomplete - put it in a .texi file and make it a
chapter of the internals manual.  (If it should be a unit smaller than a
chapter, that can always be rearranged later, but err on the side of
putting something in a separate .texi file rather than putting disparate
topics within one .texi file.)

For example, you have a section about garbage collection.  Make that a new
(small) file, gcc/doc/ggc.texi (making it a chapter, not a subsubsection,
in the internals manual, for now), with a brief FIXME there indicating the
scope of what's not covered.  Its final place will be somewhere in that
manual, and being there it's more visible for people to see and work on.  
(And, as part of the main internals manual, it's unambiguous that people
changing interfaces it documents are required to update it.)

> complying with the rules written and unwritten, I will be rewriting
> Joachim Nadler's guide to writing a front end from scratch and
> incorporating that, probably into the main gcc manual (copyright
> problems, can't get a release). At that point the treelang manual can
> become just another front end manual.

When doing this, try to work on the basis of adding structure to the
internals manual even with very incomplete contents, then filling out what
you understand bit-by-bit in the tree while leaving other parts marked as
needing filling in for people who understand those to fill in.  Again,
sourcebuild.texi is an example (and provides the overall framework within
which docs for the build system should go).  Similarly, c-tree.texi is the
framework for additional docs on the tree structures and interfaces.

-- 
Joseph S. Myers
jsm28@cam.ac.uk