This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: Creating a live, all-encompassing architectural document for GCC
On 10/26/07, Eric Weddington <eweddington@cso.atmel.com> wrote:
> <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.
Thanks. I'll take a look.
>
> 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.
That's just one option. The impedance between wiki and the source
tree is that the wiki is not patch-based, which makes it more
accessible but it also increases chances that the code and the
documentation will diverge.
I maintain that divergence is inevitable, regardless of whether the
code and the documentation live together or not (without getting into
Literate Programming arguments). So, we need to make it easy to keep
them both in sync.
Moving to a pure document extraction system like doxygen or javadoc
may be useful, but the problem there is that we miss all the
whole-system documentation, API interfaces, behaviours, etc.