This is the mail archive of the
gdb@sourceware.org
mailing list for the GDB project.
Re: A new strategy for internals documentation
- From: Eli Zaretskii <eliz at gnu dot org>
- To: John Gilmore <gnu at toad dot com>
- Cc: yao at codesourcery dot com, stanshebs at earthlink dot net, gdb at sourceware dot org
- Date: Fri, 09 Aug 2013 12:26:34 +0300
- Subject: Re: A new strategy for internals documentation
- References: <5201781A dot 3000607 at earthlink dot net> <83k3jyunt8 dot fsf at gnu dot org> <52031434 dot 2080005 at codesourcery dot com> <83k3jwt7in dot fsf at gnu dot org> <201308090129 dot r791Tw6a016114 at new dot toad dot com>
- Reply-to: Eli Zaretskii <eliz at gnu dot org>
> cc: Yao Qi <yao@codesourcery.com>, stanshebs@earthlink.net, gdb@sourceware.org
> Comments: In-reply-to Eli Zaretskii <eliz@gnu.org>
> message dated "Thu, 08 Aug 2013 20:30:24 +0300."
> Date: Thu, 08 Aug 2013 18:29:58 -0700
> From: John Gilmore <gnu@toad.com>
>
> The real issue is not about where the information is stored. The real
> issue is that people are evolving the code base without evolving the
> matching documentation.
Maybe it was so back when you started with this manual. It is no
longer the case. The real issue with this manual now is that it is
profoundly incomplete, so much so that some of the most important
parts of the GDB internals are not described at all, or their
description is just a listing of APIs without any glue.
By contrast, what _is_ there is being updated as GDB is developed, as
part of the development, and changes in GDB that invalidate what's in
the manual are accompanied by suitable changes to the manual.
> * Changes to Gdbint should not go through approval
>
> If the team agrees with this, it's easy enough for any GDB maintainer
> to merely approve gdbint changes that are submitted as patches.
The approval part is a non-issue: I usually review patches to
documentation within hours of the RFA. Note that people who mentioned
this issue didn't talk about approval, they talked about the writing
process itself.
> If [the internals manual] isn't doing that job, don't just change
> its format; change the process of updating the information, so that
> the information becomes relevant again.
People want _zero_ process on its behalf. I tried to convince them
otherwise, offering help in many ways, including those you mentioned,
but you cannot convince someone to invest any effort when they want to
invest none. So I gave up. After all, a project in general, and its
documentation in particular, cannot be better than what the project's
community wants it to be.
Once again, the main problem (and some will say it's not a problem at
all) is that the majority of GDB developers don't see any need in this
manual's existence, or in any documentation of the internals besides
what's in the comments. None whatsoever. Until this changes, there's
no hope in improving the internals' documentation, and no need to
invest any additional effort in any replacements.