After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 590927 - Support AM_SILENT_RULES for doc-build steps
Support AM_SILENT_RULES for doc-build steps
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other All
: Normal enhancement
: 1.18
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks: 580062
 
 
Reported: 2009-08-06 10:19 UTC by Philip Withnall
Modified: 2011-04-14 14:41 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Philip Withnall 2009-08-06 10:19:11 UTC
It would be nice if gtk-doc supported pretty compilation output with AM_SILENT_RULES. See: http://live.gnome.org/GnomeGoals/NicerBuilds
Comment 1 Stefan Sauer (gstreamer, gtkdoc dev) 2009-09-16 21:45:46 UTC
Like other projects I'd like to wait a bit for automake 1.11 to become more widely available. Also are you requestion that gtk-doc itself build silently or that the doc build in other modules using gtk-doc should support silent rules.

In any case I need to figure what I have to change ...
Comment 2 Philip Withnall 2009-09-16 23:42:32 UTC
I was thinking about the doc build in other modules using gtk-doc; making that silent would be nice. It should just take a good sprinkling of AM_V_GEN.
Comment 3 Stefan Sauer (gstreamer, gtkdoc dev) 2009-12-18 07:55:32 UTC
Phillip, do you know a project that has custom silent rules?
Comment 5 Stefan Sauer (gstreamer, gtkdoc dev) 2009-12-18 16:04:32 UTC
That looks easy. Now the problem is that I would need to add those to gtk-doc.make, where I have no control if the project using gtk-doc.mak is using silent rules or not. So if someone has no support for silent rules $(AM_V_GEN) becomes "" and thus shows no effect, right? I'll try this later.
Comment 6 Thomas Andersen 2010-01-18 20:37:31 UTC
(In reply to comment #5)
> That looks easy. Now the problem is that I would need to add those to
> gtk-doc.make, where I have no control if the project using gtk-doc.mak is using
> silent rules or not. So if someone has no support for silent rules $(AM_V_GEN)
> becomes "" and thus shows no effect, right? I'll try this later.

From http://www.gnu.org/software/hello/manual/automake/Options.html
"You can use the predefined variable AM_V_GEN as a prefix to commands that should output a status line in silent mode, and AM_V_at as a prefix to commands that should not output anything in silent mode. When output is to be verbose, both of these variables will expand to the empty string."
Comment 7 Stefan Sauer (gstreamer, gtkdoc dev) 2010-04-06 14:43:35 UTC
this is the current output. I could remove/change the echo lines (gtk-doc: ...).
Most of the other lines are from docbook xsl and dblatex.

gtk-doc: Scanning header files
gtk-doc: Compiling scanner
  CC    buzztard-cmd-scan.o
gtk-doc: Linking scanner
  LINK  buzztard-cmd-scan
gtk-doc: Running scanner buzztard-cmd-scan

gtk-doc: Building XML
./buzztard-cmd-unused.txt:1: warning: 6 unused declarations.They should be added to buzztard-cmd-sections.txt in the appropriate place.
gtk-doc: Building HTML
Computing chunks...
Writing pr01.html for preface
Writing pt01.html for part
Writing buzztard-cmd-btcmd.html for refentry(buzztard-cmd-btcmd)
Writing BtCmdApplication.html for refentry(BtCmdApplication)
Writing uibtcmd.html for reference(uibtcmd)
Writing objecttree.html for chapter(objecttree)
Writing api-index.html for index(api-index)
Writing pt02.html for part
Writing index.html for book(index)
Writing index.sgml for book(index)
Writing buzztard-cmd.devhelp for book(index)
Writing buzztard-cmd.devhelp2 for book(index)
gtk-doc: Fixing cross-references
gtk-doc: Building PDF
/usr/share/dblatex/lib/dbtexmf/dblatex/grubber/util.py:8: DeprecationWarning: the md5 module is deprecated; use hashlib instead
  import md5
Build the book set list...
Build the listings...
XSLT stylesheets DocBook - LaTeX 2e (0.2.11-1)
===================================================
link not supported in programlisting or screen
returnvalue not supported in programlisting or screen
...
Build buzztard-cmd-docs.sgml.pdf
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
processing index /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.idx...
This is makeindex, version 2.14 [02-Oct-2002] (kpathsea + Thai support).
Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored).
Scanning input file /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.idx....done (7 entries accepted, 0 rejected).
Sorting entries....done (27 comparisons).
Generating output file /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.ind....done (12 lines written, 0 warnings).
Output written in /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.ind.
Transcript written in /tmp/tmpHxyyeP/buzztard-cmd-docs.sgml.ilg.
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
'buzztard-cmd.pdf' successfully built


I tried to changie it localy but it would now look like:
test -z "buzztard-cmd.args buzztard-cmd.hierarchy buzztard-cmd.interfaces buzztard-cmd.prerequisites buzztard-cmd.signals buzztard-cmd-undocumented.txt buzztard-cmd-undeclared.txt buzztard-cmd-unused.txt scan-build.stamp sgml-build.stamp html-build.stamp pdf-build.stamp ./sgml.stamp ./html.stamp ./pdf.stamp" || rm -f buzztard-cmd.args buzztard-cmd.hierarchy buzztard-cmd.interfaces buzztard-cmd.prerequisites buzztard-cmd.signals buzztard-cmd-undocumented.txt buzztard-cmd-undeclared.txt buzztard-cmd-unused.txt scan-build.stamp sgml-build.stamp html-build.stamp pdf-build.stamp ./sgml.stamp ./html.stamp ./pdf.stamp
rm -rf .libs _libs
  GEN    clean-local
  GEN    clean-local
rm -f *.lo
  GEN    scan-build.stamp
gtk-doc: Scanning header files
  GEN    scan-build.stamp
  GEN    scan-build.stamp
  GEN    scan-build.stamp
gtk-doc: Compiling scanner
libtool: compile:  gcc -g -O2 -I../../../src/lib/core -I../../../src/lib/ic -I../../../src/ui/cmd -I../../.. -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -I/usr/include/gstreamer-0.10 -DORBIT2=1 -pthread -I/usr/include/gconf/2 -I/usr/include/orbit-2.0 -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -pthread -I/home/ensonic/buzztard/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/gstreamer-0.10 -I/home/ensonic/buzztard/include -DDBUS_API_SUBJECT_TO_CHANGE -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/hal -I/usr/include/libgsf-1 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -O0 -Wall -Werror -g -g -O2 -c buzztard-cmd-scan.c  -fPIC -DPIC -o .libs/buzztard-cmd-scan.o
libtool: compile:  gcc -g -O2 -I../../../src/lib/core -I../../../src/lib/ic -I../../../src/ui/cmd -I../../.. -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -I/usr/include/gstreamer-0.10 -DORBIT2=1 -pthread -I/usr/include/gconf/2 -I/usr/include/orbit-2.0 -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -pthread -I/home/ensonic/buzztard/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/gstreamer-0.10 -I/home/ensonic/buzztard/include -DDBUS_API_SUBJECT_TO_CHANGE -I/usr/include/dbus-1.0 -I/usr/lib/dbus-1.0/include -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/hal -I/usr/include/libgsf-1 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/libxml2 -O0 -Wall -Werror -g -g -O2 -c buzztard-cmd-scan.c -o buzztard-cmd-scan.o >/dev/null 2>&1
gtk-doc: Linking scanner
libtool: link: gcc -g -O2 -o .libs/buzztard-cmd-scan .libs/buzztard-cmd-scan.o -pthread -Wl,--export-dynamic -pthread -Wl,--export-dynamic -Wl,--warn-common  ../../../src/lib/core/.libs/libbuzztard-core.so ../../../src/lib/ic/.libs/libbuzztard-ic.so ../../../src/ui/cmd/.libs/libbtcmd.a /usr/lib/libgstcontroller-0.10.so /usr/lib/libgstbase-0.10.so /usr/lib/libgconf-2.so -L/home/ensonic/buzztard/lib /home/ensonic/buzztard/lib/libgstbuzztard.so /usr/lib/libgstreamer-0.10.so /usr/lib/libgmodule-2.0.so /usr/lib/libgthread-2.0.so /home/ensonic/buzztard/lib/libbml.so -L/lib -ldbus-glib-1 -lhal -ldbus-1 -lpthread -lgsf-1 /usr/lib/libgobject-2.0.so /usr/lib/libxml2.so /usr/lib/libglib-2.0.so -lrt -pthread  -Wl,-rpath -Wl,/home/ensonic/buzztard/lib
gtk-doc: Running scanner buzztard-cmd-scan
  GEN    scan-build.stamp
  GEN    sgml-build.stamp
gtk-doc: Building XML
  GEN    sgml-build.stamp
  GEN    sgml-build.stamp
./buzztard-cmd-unused.txt:1: warning: 6 unused declarations.They should be added to buzztard-cmd-sections.txt in the appropriate place.
  GEN    sgml-build.stamp
  GEN    html-build.stamp
gtk-doc: Building HTML
  GEN    html-build.stamp
  GEN    html-build.stamp
  GEN    html-build.stamp
  GEN    html-build.stamp
Computing chunks...
Writing pr01.html for preface
Writing pt01.html for part
Writing buzztard-cmd-btcmd.html for refentry(buzztard-cmd-btcmd)
Writing BtCmdApplication.html for refentry(BtCmdApplication)
Writing uibtcmd.html for reference(uibtcmd)
Writing objecttree.html for chapter(objecttree)
Writing api-index.html for index(api-index)
Writing pt02.html for part
Writing index.html for book(index)
Writing index.sgml for book(index)
Writing buzztard-cmd.devhelp for book(index)
Writing buzztard-cmd.devhelp2 for book(index)
  GEN    html-build.stamp
  GEN    html-build.stamp
gtk-doc: Fixing cross-references
  GEN    html-build.stamp
  GEN    html-build.stamp
  GEN    pdf-build.stamp
gtk-doc: Building PDF
  GEN    pdf-build.stamp
  GEN    pdf-build.stamp
  GEN    pdf-build.stamp
/usr/share/dblatex/lib/dbtexmf/dblatex/grubber/util.py:8: DeprecationWarning: the md5 module is deprecated; use hashlib instead
  import md5
Build the book set list...
Build the listings...
XSLT stylesheets DocBook - LaTeX 2e (0.2.11-1)
===================================================
link not supported in programlisting or screen
returnvalue not supported in programlisting or screen
parameter not supported in programlisting or screen
...
Build buzztard-cmd-docs.sgml.pdf
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
processing index /tmp/tmpjErovr/buzztard-cmd-docs.sgml.idx...
This is makeindex, version 2.14 [02-Oct-2002] (kpathsea + Thai support).
Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored).
Scanning input file /tmp/tmpjErovr/buzztard-cmd-docs.sgml.idx....done (7 entries accepted, 0 rejected).
Sorting entries....done (27 comparisons).
Generating output file /tmp/tmpjErovr/buzztard-cmd-docs.sgml.ind....done (12 lines written, 0 warnings).
Output written in /tmp/tmpjErovr/buzztard-cmd-docs.sgml.ind.
Transcript written in /tmp/tmpjErovr/buzztard-cmd-docs.sgml.ilg.
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
This is pdfTeXk, Version 3.141592-1.40.3 (Web2C 7.5.6)
 %&-line parsing enabled.
entering extended mode
'buzztard-cmd.pdf' successfully built
  GEN    pdf-build.stamp
Comment 8 Philip Withnall 2010-04-06 15:17:01 UTC
Ideally that compilation would output something like the following (though I'm not sure whether all of them should use "DOC" rather than something like "HTML" or "PDF"):

  DOC   Scanning header files
  CC    buzztard-cmd-scan.o
  LINK  buzztard-cmd-scan
  DOC   Running scanner buzztard-cmd-scan
  DOC   Building XML
./buzztard-cmd-unused.txt:1: warning: 6 unused declarations.They should be
added to buzztard-cmd-sections.txt in the appropriate place.
  DOC   Building HTML
  DOC   pr01.html for preface
  DOC   pt01.html for part
  DOC   buzztard-cmd-btcmd.html for refentry(buzztard-cmd-btcmd)
  DOC   BtCmdApplication.html for refentry(BtCmdApplication)
  DOC   uibtcmd.html for reference(uibtcmd)
  DOC   objecttree.html for chapter(objecttree)
  DOC   api-index.html for index(api-index)
  DOC   pt02.html for part
  DOC   index.html for book(index)
  DOC   index.sgml for book(index)
  DOC   buzztard-cmd.devhelp for book(index)
  DOC   buzztard-cmd.devhelp2 for book(index)
  DOC   Fixing cross-references
  DOC   Building PDF

You can create a custom "DOC" rule with the following code:

V_DOC = $(V_DOC_$(V))
V_DOC_ = $(V_DOC_$(AM_DEFAULT_VERBOSITY))
V_DOC_0 = echo "  DOC   " $@;
Comment 9 Javier Jardón (IRC: jjardon) 2010-12-01 15:37:53 UTC
Stefan: any news about this? It would be great to have this for 1.16 ;)
Comment 10 Stefan Sauer (gstreamer, gtkdoc dev) 2011-04-13 09:18:47 UTC
I still totally fail to understand how I am supposed to apply the tips from the links:

Obviously I can change some echo. But then

make[3]: Betrete Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl'
  DOC   12:09:07.660039263: Scanning header files
  DOC   12:09:07.721268464: Introspecting gobjects
gtk-doc: Compiling scanner
libtool: compile:  gcc -g -O2 -Wall -I../../../tests/gobject/src -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -g -O2 -Wall -c tester-scan.c  -fPIC -DPIC -o .libs/tester-scan.o
libtool: compile:  gcc -g -O2 -Wall -I../../../tests/gobject/src -pthread -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -g -O2 -Wall -c tester-scan.c -o tester-scan.o >/dev/null 2>&1
gtk-doc: Linking scanner
libtool: link: gcc -g -O2 -Wall .libs/tester-scan.o -pthread -o tester-scan  /usr/lib/libgobject-2.0.so /usr/lib/libgthread-2.0.so -lrt /usr/lib/libglib-2.0.so ../../../tests/gobject/src/.libs/libtester.a -pthread 
gtk-doc: Running scanner tester-scan

The lines between "gtk-doc: Compiling scanner" and "gtk-doc: Running scanner tester-scan" come from gtkdoc-scangobj, how can any V_DOC or AM_GEN affect printf statements inside this tool.


Further V_DOC_0 = echo "  DOC   " $@; does not make sense imho, as it would print stuff like:
  DOC xxx-build.stamp
which is not meaningful to the user.


In the html step, the output like:
Computing chunks...
Writing intro.html for preface(intro)
Writing Overview-building.html for chapter(Overview-building)

comes from the docbook stylesheets. Are you sugestting that I pass $(AM_DEFAULT_VERBOSITY) to the gtk-doc tools and try to use sed scripts to mange the output of the tools I am calling?
Comment 11 Stefan Sauer (gstreamer, gtkdoc dev) 2011-04-13 13:45:00 UTC
This is how it looks right now (intentionally with some warnings):
- need to check the remaining messages from the html docbook stylesheets
- wrote an email to dblatex devel to see if we can trim the output there

make[2]: Betrete Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl'
  DOC   Scanning header files
  DOC   Introspecting gobjects
  DOC   Rebuilding template files
  DOC   Building XML
  DOC   Building HTML
../xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined
<refsect2 id="GtkdocEnum" role="enum">
                                     ^
Computing chunks...
Warning: multiple "IDs" for constraint linkend: GtkdocEnum.
Warning: multiple "IDs" for constraint linkend: GtkdocEnum.
Warning: multiple "IDs" for constraint linkend: GtkdocEnum.
Warning: multiple "IDs" for constraint linkend: GtkdocEnum.
Warning: multiple "IDs" for constraint linkend: GtkdocEnum.
Writing index.sgml for book(index)
Writing tester.devhelp for book(index)
Writing tester.devhelp2 for book(index)
  DOC   Fixing cross-references
  DOC   Building PDF
/usr/share/dblatex/lib/dbtexmf/dblatex/grubber/util.py:8: DeprecationWarning: the md5 module is deprecated; use hashlib instead
  import md5
Build the book set list...
/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl/xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined
<refsect2 id="GtkdocEnum" role="enum">
                                     ^
Build the listings...
/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl/xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined
<refsect2 id="GtkdocEnum" role="enum">
                                     ^
/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl/xml/types.xml:42: element refsect2: validity error : ID GtkdocEnum already defined
<refsect2 id="GtkdocEnum" role="enum">
                                     ^
XSLT stylesheets DocBook - LaTeX 2e (0.3-1)
===================================================
Build tester-docs.pdf
processing index /tmp/tmpgIolyY/tester-docs.idx...
This is makeindex, version 2.15 [TeX Live 2009] (kpathsea + Thai support).
Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored).
Scanning input file /tmp/tmpgIolyY/tester-docs.idx....done (26 entries accepted, 0 rejected).
Sorting entries....done (124 comparisons).
Generating output file /tmp/tmpgIolyY/tester-docs.ind....done (30 lines written, 0 warnings).
Output written in /tmp/tmpgIolyY/tester-docs.ind.
Transcript written in /tmp/tmpgIolyY/tester-docs.ilg.
make[2]: Verlasse Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs-tmpl'
Comment 12 Philip Withnall 2011-04-13 17:09:23 UTC
(In reply to comment #11)
> This is how it looks right now (intentionally with some warnings):
> - need to check the remaining messages from the html docbook stylesheets
> - wrote an email to dblatex devel to see if we can trim the output there

That looks like a good start. I believe the usual tactic for dealing with programs like dblatex is to (iff silent mode is enabled) either:
 1. pass a --silent option to the program, or
 2. pipe the program's output to /dev/null.

From a quick look at dblatex's man page, it doesn't seem to have a --silent option, so I guess the best we could do at the moment would be to pipe its stdout to /dev/null iff silent mode is enabled. Obviously, if the verbosity was increased (e.g. make was called with V=1), the output of dblatex shouldn't be piped to /dev/null.

Makefile.introspection has a decent example of conditionally passing options to programs depending on the verbosity level, and it shouldn't be hard to extend this to conditionally piping output:

http://git.gnome.org/browse/gobject-introspection/tree/Makefile.introspection#n66
Comment 13 Stefan Sauer (gstreamer, gtkdoc dev) 2011-04-14 07:01:48 UTC
This it the mail to dblatex-devel for reference:
http://sourceforge.net/mailarchive/forum.php?thread_name=4DA5A43F.5030305%40hora-obscura.de&forum_name=dblatex-devel

I am already redirecting stdout to >/dev/null for silent mode:
http://git.gnome.org/browse/gtk-doc/tree/gtkdoc-mkpdf.in#n99

Unfortunately that does not work, if the tool in question exec other tools with new file-descriptors.

Thanks got the link, I'll see if I can find something nice in there.
Comment 14 Stefan Sauer (gstreamer, gtkdoc dev) 2011-04-14 14:41:36 UTC
make[2]: Betrete Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs'
  DOC   Scanning header files
  DOC   Introspecting gobjects
  DOC   Building XML
  DOC   Building HTML
  DOC   Fixing cross-references
  DOC    Building PDF
XSLT stylesheets DocBook - LaTeX 2e (0.3-1)
===================================================
This is makeindex, version 2.15 [TeX Live 2009] (kpathsea + Thai support).
Scanning style file /usr/share/dblatex/latex/scripts/doc.ist....done (4 attributes redefined, 0 ignored).
Scanning input file /tmp/tmpSbqKOH/tester-docs.idx....done (26 entries accepted, 0 rejected).
Sorting entries....done (124 comparisons).
Generating output file /tmp/tmpSbqKOH/tester-docs.ind....done (30 lines written, 0 warnings).
Output written in /tmp/tmpSbqKOH/tester-docs.ind.
Transcript written in /tmp/tmpSbqKOH/tester-docs.ilg.
make[2]: Verlasse Verzeichnis '/home/ensonic/projects/gnome/gtk-doc/tests/gobject/docs'

This is with two patches for dblatex (submitted upstream). Two more patches and the remaining spam should be gone. I will declare this bug as closed already.