[PATCH] gdb/doc: use silent-rules.mk in the Makefile

[Eli Zaretskii]

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Fri, 12 Apr 2024 23:32:28 +0100
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >>  gdb/doc/Makefile.in | 158 ++++++++++++++++++++++++--------------------
> >>  gdb/silent-rules.mk |   1 +
> >>  2 files changed, 86 insertions(+), 73 deletions(-)
> >
> > Doesn't this silence too much?  Can you should the output of each rule
> > after the changes?
> 
> Yes you can.  As with the rest of GDB, if you do:
> 
>   make all-gdb V=1

Yes, I know.  But that's not what I meant, sorry for being unclear.  I
meant to ask _you_ to show the output of each rule that you change to
be silent, so that I could compare that with what it outputs
un-silenced, and decide whether we remove too much from the output.

I've now tried to figure that out by reading the silent-rules.mk
macros, and I feel that, indeed, in some cases we silence too much,
without (IMO) a good reason.  For example:

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

This completely conceals the fact that we run texi2pod and pod2man,
ending with just a single vague

   GEN gdb.1

I think significant commands should be shown to the user, for better
"situational awareness".  The analogy with compilation and linking
here, if that's what served the model for these changes, is IMO
incomplete: when we compile or link, seeing just "CXX foo.o" or
"CXXLD gdb" is enough to tell us what happens, whereas with the
generic "GEN foo" we don't really know what happens at all.

So my preference would be for having the above emit something like the
below instead

  TEXI2POD gdb.pod
  POD2MAN1 gdb.1

And similarly with the likes of

>  annotate.pdf: $(ANNOTATE_DOC_FILES)
> -	rm -f $(ANNOTATE_TEX_TMPS)
> -	$(TEXI2DVI) --pdf -I $(srcdir) $(srcdir)/annotate.texinfo
> +	$(SILENCE) rm -f $(ANNOTATE_TEX_TMPS)
> +	$(ECHO_GEN) $(TEXI2DVI) $(SILENT_QUIET_FLAG) --pdf -I $(srcdir) \
> +		$(srcdir)/annotate.texinfo

Why emit just

  GEN annotate.pdf

?  I'd prefer something like

  TEXI2DVI annotate.pdf

instead.

Does this make sense?