[rfa:doco] Doco problems with level two annotations

[Andrew Cagney]

> Date: Fri, 16 May 2003 20:18:44 -0400
>> From: Andrew Cagney <ac131313@redhat.com>
>> 
>> The attached updates the gdb/doc/annotate.texi file (renaming it to
>> annotate.texinfo) so that it is a standalone document that:
>> 
>> - notes the limitations of level two annotations
>> - points the user at gdb/mi
>> - mentions the mi features that have replaced level two annotation
>> functionality
> 
> 
> I have several comments about this.
> 
> Is it really useful to have this as a separate manual?  Why not move
> the text into an appendix instead?  It would simplify the change, for
> starters.  You didn't show the Makefile.in patch, but it would become
> unnecessary.  The changes of @section to @chapter would also become
> unnecessary.  Finally, when we eventually remove level-2 annotations
> entirely, you won't need to modify any configury, just delete the
> appendix and all references to it.

I could use the magic raise/lower sections command, as could the person 
that first merged this doco into gdb.texinfo, however lets ignore that :-)

I'm expecting this ``paper'' to be around for several years, and to 
evolve.  I don't expect the paper's audience to be very large (much 
smaller than even the remote protocol audience even!)

Anyway, the real reason is that I happen to know that the GNU Press 
person would like the GDB group to try to keep the basic user manual 
trim.  Its current size (relative to GCC and EMACS) allows it to be 
printed using a cheaper form factor, and that in turn makes it possible 
for it to be sold at a lower price.  If GDB's manual gets too large then 
it will be forced into a more expensive form factor (there is some 
slack) and that would likely reflect on both the books cost and its 
popularity (I think it's GNU Press's second most popular book after EMACS!).

If the ``paper'' is going to be turned into an appendix then I'd need to 
put a bit more effort into it - both to clean it up more and ensure that 
it isn't too bulky (If you can't guess, I'm not very motivated :-( ).

But, yes I see your point.  So ....?

(I'll fix the typos.)

Andrew