> -----Original Message----- > From: Diego Novillo [mailto:[EMAIL PROTECTED] > Sent: Friday, October 26, 2007 11:10 AM > To: gcc@gcc.gnu.org > Subject: RFC: Creating a live, all-encompassing architectural > document for GCC > > > It should be easy for an individual maintainer (or even user) to go in > and modify parts of the document that are incomplete/missing/wrong. > This and navigability suggest a wikipedia-like approach. We even have > the beginnings of some of this in the wiki, so I would like to build > on that. ... > However, if > a patch refactors a module and its internal interfaces are changed, > then the patch should be accompanied with a change to the > documentation. ... > The documentation for individual modules and files should be linked to > the actual source code. Perhaps this could be automatically generated > with tools like javadoc or doxygen. ... > So, I think my inclination is to provide this document as a wiki.
I like the goals. But what I see above seems mutually exclusive. It's reasonable to include doxygen, and change the code with the documentation simultaneously. Here's the avr-libc user manual online as an example of the output: <http://www.nongnu.org/avr-libc/user-manual/> It certainly meets the navigable requirement. I'm sure all of you have seen other examples as well. But you also want the user to be able to change an internals document via a wiki? How does this work with a patch system? How do you propose to resolve conflicts between a user edit, and maintainer's patch? Maybe I'm ignorant to the capabilities of a wiki, but this is where it sounds like incompatible systems. Eric Weddington
