Re: FYI: minsyms documentation

[Eli Zaretskii <eliz at gnu dot org>]

> From: Tom Tromey <tromey@redhat.com>
> Cc: Stan Shebs <stanshebs@earthlink.net>, gdb-patches@sourceware.org
> Date: Mon, 02 Jan 2012 15:07:51 -0700
> 
> >>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:
> 
> Stan> Are newbies learning by reading the manual, or reading the code?
> 
> Eli> What newbies?  The people who hack at the core features of GDB can be
> Eli> counted on fingers of a single hand, and they didn't change in years.
> 
> There have been multiple new contributors since I started seriously
> working on GDB 3 years ago.

I was not talking about contributors.  I was talking about people who
dare hacking at the core features and making structural changes that
cross boundaries of APIs.

> Eli> Again, the current content of that manual can only do a mis-service,
> Eli> so redistributing it is wasted effort.
> 
> This is not entirely true.  Some of gdbint.texinfo is badly out of date,
> but some of it is still relevant.

Without a clear markings which are which, and with large parts of it
badly outdated, it is still a reader-unfriendly document, reading
which runs a very high risk of learning misleading or downright
incorrect information.

Emacs development has a habit that a release requires careful review
of the documentation for inaccuracies, stale or incorrect information,
etc.  We don't have such process; perhaps we should introduce it.

> For example, it is still the only documentation for ui-out and for
> cleanups

I'm willing to bet that even these parts are no longer entirely
accurate or complete, even though at the time they were written, they
were exemplary stuff.

> due to licensing, I think that text cannot be moved into comments in
> the code without special dispensation from the FSF.

This problem can be easily solved: read the text in the manual, close
it, then write the docs in the source files without looking at the
manual, but just at the code.  The result will be different enough
from the original to side-step the copyright issue.  If needed,
another person (e.g., me) can edit the comments to remove any
semblance to the original that sneak in.