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 681336 - man pages not built if --enable-gtk-doc not specified
man pages not built if --enable-gtk-doc not specified
Status: RESOLVED FIXED
Product: glib
Classification: Platform
Component: docs
2.31.x
Other Linux
: Normal normal
: ---
Assigned To: gtkdev
gtkdev
Depends on:
Blocks:
 
 
Reported: 2012-08-06 21:39 UTC by Dominique Leuenberger
Modified: 2012-08-16 22:06 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
make --enable-man independent (798 bytes, patch)
2012-08-08 14:08 UTC, Matthias Clasen
accepted-commit_now Details | Review
Clean up man pages on clean (1.54 KB, patch)
2012-08-08 14:08 UTC, Matthias Clasen
accepted-commit_now Details | Review
no more placeholders (3.57 KB, patch)
2012-08-08 14:09 UTC, Matthias Clasen
accepted-commit_now Details | Review
Remove man page placeholder generation (3.61 KB, patch)
2012-08-16 22:06 UTC, Matthias Clasen
committed Details | Review
Clean up man pages on 'clean' (1.58 KB, patch)
2012-08-16 22:06 UTC, Matthias Clasen
committed Details | Review
Make --enable-man and --enable-gtk-doc independent (843 bytes, patch)
2012-08-16 22:06 UTC, Matthias Clasen
committed Details | Review

Description Dominique Leuenberger 2012-08-06 21:39:27 UTC
The command line
./configure --enable-man verifies if xsltproc and the stylesheets are available, which is all fine..

But due to Makefile.am in docs having
if ENABLE_GTK_DOC
SUBDIRS = reference
endif

the man pages, which also live in the reference subfolder, to not get built/installed, which is contradicting the expectations from configure success.

Passing --enable-man --enable-gtk-doc indeed does solve the issue and man pages are being generated and installed.
Comment 1 Colin Walters 2012-08-07 21:46:03 UTC
This is a regression introduced by:

$ git show 9f9ab640306da52127935bd8eab82a1a8dcaaf89
commit 9f9ab640306da52127935bd8eab82a1a8dcaaf89
Author: Matthias Clasen <mclasen@redhat.com>
Date:   Thu Aug 2 23:52:46 2012 +0200

    Rework the man page configury

for people building from tarballs.

Maybe a better default would be to default to rebuilding only if .git is found or something, but that gets messy.

Conceptually though, we should decouple man pages from gtk-doc.  They should be moved out out of docs/reference into say docs/man.
Comment 2 Allison Karlitskaya (desrt) 2012-08-07 22:14:01 UTC
Worth noting that I just committed a patch to dconf that added manpages and included them as subsections in the reference documentation.  I'm not sure that makes sense, but it's kinda useful in a way...
Comment 3 Matthias Clasen 2012-08-08 01:46:37 UTC
(In reply to comment #1)

> Conceptually though, we should decouple man pages from gtk-doc.  They should be
> moved out out of docs/reference into say docs/man.

I disagree. I really really want the information that is available in man page form to be included in the online reference docs as well.

If that means that not building reference docs implies not building man pages, that is a price that I'm willing to pay.
Comment 4 Dominique Leuenberger 2012-08-08 11:39:57 UTC
for me as user, the following is all acceptable:

- If --enable-man is specified, configure aborts if gtk-doc is not there (so you can depend on it.. the abort condition is different to today, where it's quietly ignored)
- Installation of the man pages (prebuilt, as they are now shiped it seems) is easily made possible
Comment 5 Matthias Clasen 2012-08-08 14:08:00 UTC
I'm not really fond of the pre-built idea anymore, and I also don't think the placeholder generation that we currently have is worth the Makefile.am space.
Comment 6 Matthias Clasen 2012-08-08 14:08:28 UTC
Created attachment 220681 [details] [review]
make --enable-man independent
Comment 7 Matthias Clasen 2012-08-08 14:08:52 UTC
Created attachment 220682 [details] [review]
Clean up man pages on clean
Comment 8 Matthias Clasen 2012-08-08 14:09:11 UTC
Created attachment 220683 [details] [review]
no more placeholders
Comment 9 Matthias Clasen 2012-08-08 14:09:29 UTC
Here's some patches to that effect - review appreciated
Comment 10 Colin Walters 2012-08-08 14:30:18 UTC
Review of attachment 220681 [details] [review]:

But doesn't this break the --disable-gtk-doc case (which note, jhbuild defaults to)?

Update: Just checked, appears to work Ok.
Comment 11 Colin Walters 2012-08-08 14:31:21 UTC
Review of attachment 220682 [details] [review]:

Right.

::: docs/reference/gio/Makefile.am
@@ +180,3 @@
 endif
 
+CLEANFILES += $(man_MANS)

There is no BUILT_SOURCES it looks like, so deleting it from MAINTAINERCLEANFILES should be ok.
Comment 12 Colin Walters 2012-08-08 14:33:31 UTC
Review of attachment 220683 [details] [review]:

It looks like the original code dates to:

commit 54f796b1b6e161e92b975e25f06c3a5b7121179d
Author: Matthias Clasen <maclas@gmx.de>
Date:   Tue Jun 17 23:08:37 2003 +0000

    New macros to check for XML catalog contents and path, borrowed from

But there's no rationale there.  I agree with you though - the stubs are stupid.  If you want man pages, install the tools.  If you don't, disable them.
Comment 13 Matthias Clasen 2012-08-16 22:06:07 UTC
The following fixes have been pushed:
b60168a Remove man page placeholder generation
4cd5a63 Clean up man pages on 'clean'
ce53130 Make --enable-man and --enable-gtk-doc independent
Comment 14 Matthias Clasen 2012-08-16 22:06:10 UTC
Created attachment 221503 [details] [review]
Remove man page placeholder generation

I don't see a good reason for this - if man page generation is
disabled, man pages are not produced, and things like 'make dist'
will fail. That is simpler and better.
Comment 15 Matthias Clasen 2012-08-16 22:06:13 UTC
Created attachment 221504 [details] [review]
Clean up man pages on 'clean'

Follow the automake heuristic that says "if 'make' created it,
'make clean' should remove it".
Comment 16 Matthias Clasen 2012-08-16 22:06:16 UTC
Created attachment 221505 [details] [review]
Make --enable-man and --enable-gtk-doc independent

Previously, --enable-man --disable-gtk-doc would silently skip
man page generation, because we didn't even desdend into docs/reference.
Fix this by always going there.