Re: Re: Some notes on the Wiki

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Mon, 11 Jul 2005, Michael Cieslinski wrote:

> I also could convert parts of the ggcinternals manual into wiki pages.
> But only if there is a consensus about this being the way to go.

I'm sure it's the wrong way to go.  I find a properly formatted and 
indexed book far more convenient for learning about substantial areas of 
compiler internals, or for finding what some particular macro is specified 
to do, than a wiki.  And since some people seem to think the internal 
manual is of no use: it's the first place I refer to for information on 
the areas of internals it covers; after that source code and mailing list 
archives, the wiki very rarely.

I think the wiki is certainly useful for rough notes such as 
<http://gcc.gnu.org/wiki/general%20backend%20cleanup>, synthesised from 
mailing list discussions.

It may be useful as an intermediate step in putting together 
reverse-engineered information about internals in order to specify it 
properly in the internals manual - but only provided authorship and 
copyright assignment information is rigorously tracked as required by the 
FSF.

But in general internals documentation should include the *specification* 
written before the implementation and submitted with it for review 
together, and the specification should not need to be reverse-engineered 
later (see Kenner's comments passim about the importance of comments being 
written at the time of code or at least by its author, not backfilled 
later).

-- 
Joseph S. Myers               http://www.srcf.ucam.org/~jsm28/gcc/
    jsm@polyomino.org.uk (personal mail)
    joseph@codesourcery.com (CodeSourcery mail)
    jsm28@gcc.gnu.org (Bugzilla assignments and CCs)