Re: [PATCH 2/3] gdbserver: allow the --debug command line option to take a value

[Andrew Burgess <aburgess@redhat.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Andrew Burgess <aburgess@redhat.com>
>> Cc: gdb-patches@sourceware.org
>> Date: Thu, 30 Nov 2023 18:31:24 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> +Each @var{option} is the name of a component for which debugging
>> >> +should be enabled.  The list of possible options is @option{all},
>> >> +@option{threads}, @option{event-loop}, @option{remote}.  The special
>> >> +option @option{all} enables all components.  The option list is
>> >> +processed left to right, and an option can be prefixed with the
>> >> +@kbd{-} character to disable output for that component, so you could write:
>> >> +
>> >> +@smallexample
>> >> +target> gdbserver --debug=all,-event-loop
>> >> +@end smallexample
>> >> +
>> >> +@noindent to turn on debug output for all components except @option{event-loop}.
>> >
>> > Why do we need this duplicate description?  I'd prefer to have a short
>> > sentence with a cross-reference to the previous description, so that
>> > we could have only one of them, not two.
>> 
>> This is unfortunate.  One of these instances is the general gdb info
>> manual, while the second of these is the gdbserver man page.
>
> The above is from the manual, and in Texinfo, not from the man page.
> How is the man page relevant?

The man page is generated from gdb.texinfo using this magic in
gdb/doc/Makefile.in:

  gdbserver.1: $(GDB_DOC_FILES)
  	touch $@
  	-$(TEXI2POD) $(MANCONF) -Dgdbserver < $(srcdir)/gdb.texinfo > gdbserver.pod
  	-($(POD2MAN1) gdbserver.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
  		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
  	rm -f gdbserver.pod

If from a top-level binutils-gdb build directory you do:

  make -C gdb/doc man

you'll then be able to do:

 man gdb/doc/gdbserver.1

and in that man-page you'll find that one of the blocks of my change are
present.  Note that my patch doesn't touch any other files in gdb/doc,
so we can be sure this is all coming from gdb.texinfo.

Similarly, if you:

 make -C gdb/doc info

and then:

 info gdb/doc/gdb.info

and then search for "Man Pages", you'll see that the man-pages for each
tool are included in the info manual.

Thanks,
Andrew

>
>> I guess we could restructure things somehow so that the man page part is
>> used in some way such that the duplication is removed?  But that seems
>> like a bigger refactoring task; there is already lots of duplication
>> between the man page and the info manual, so I think trying to solve the
>> problem just for this one option doesn't make much sense.
>
> I meant duplication in the manual, not between the manual and the man
> page.