Bug 36156

Summary:	improve build system for docs
Product:	dbus	Reporter:	Simon McVittie <smcv>
Component:	core	Assignee:	Simon McVittie <smcv>
Status:	RESOLVED FIXED	QA Contact:
Severity:	enhancement
Priority:	medium	CC:	rob.taylor, will
Version:	1.4.x	Keywords:	patch
Hardware:	Other
OS:	All
URL:	http://cgit.freedesktop.org/~smcv/dbus/log/?h=doc-build-36156
Whiteboard:
i915 platform:		i915 features:
Bug Depends on:
Bug Blocks:	36074
Attachments:	configure.ac: fix check for xsltproc Install dbus.devhelp to $(htmldir), not $(apidir), and remove it in clean Install xmlto output to $(htmldir) automatically Install diagram.*, system-activation.txt to the $(docdir) Install man2html output to $(htmldir) Uninstall the installed docs

Description Simon McVittie 2011-04-12 05:19:51 UTC

Some bugs in the documentation build:

- xsltproc isn't detected correctly

- dbus.devhelp should be installed to $(htmldir), not $(apidir), since it
  is an index for the spec and tutorial as well as the API docs
  (and the relative paths assume that location)

- various of the other docs could be installed automatically

The patches I'm about to attach will install:

- the xmlto-generated docs (FAQ, spec, test plan, tutorial)

- *.1.html (HTMLized man pages)

- diagram.*

- system-activation.txt

They will not install the following things which are in dbus-docs.tar.gz:

- DTDs: I'm not sure how useful these are as documentation

- Docbook source for the xmlto-generated docs: the HTML seems more useful
  for everyone except D-Bus developers

- dcop-howto.txt: we're not DCOP :-) and this seems to only be there
  for reference/inspiration

- introspect.xsl: not actually documentation, although it could be used in
  our build system one day

- ../README, ../NEWS, ../ChangeLog: if Debian is anything to go by,
  distributions tend to have their own mechanisms to copy these

- ../AUTHORS: not amazingly useful since it's auto-generated from git,
  so it lists everyone who has ever touched D-Bus

- ../COPYING: distributions tend to have their own way to document
  copyright/licensing status

- ../HACKING: anyone who'll be reading this wants the source anyway

Comment 1 Simon McVittie 2011-04-12 05:20:43 UTC

Created attachment 45516 [details] [review]
configure.ac: fix check for xsltproc

Pre-setting XSLTPROC interferes with AC_CHECK_PROGS letting the user
override choice of program via the environment.

Comment 2 Simon McVittie 2011-04-12 05:20:58 UTC

Created attachment 45517 [details] [review]
Install dbus.devhelp to $(htmldir), not $(apidir), and remove it in clean

It needs to be in $(htmldir) so that its relative paths will work.

Comment 3 Simon McVittie 2011-04-12 05:21:14 UTC

Created attachment 45518 [details] [review]
Install xmlto output to $(htmldir) automatically

Also rename HTML_FILES to XMLTO_OUTPUT, as a more self-describing name:
we have other HTML files which are not the output from xmlto.

Comment 4 Simon McVittie 2011-04-12 05:21:33 UTC

Created attachment 45519 [details] [review]
Install diagram.*, system-activation.txt to the $(docdir)

Comment 5 Simon McVittie 2011-04-12 05:22:29 UTC

Created attachment 45520 [details] [review]
Install man2html output to $(htmldir)

Comment 6 Simon McVittie 2011-04-12 05:22:46 UTC

Created attachment 45521 [details] [review]
Uninstall the installed docs

Comment 7 Will Thompson 2011-07-18 11:12:09 UTC

Review of attachment 45516 [details] [review]:

++

Comment 8 Will Thompson 2011-07-18 11:16:03 UTC

Review of attachment 45517 [details] [review]:

Yup.

Comment 9 Will Thompson 2011-07-18 11:17:21 UTC

Review of attachment 45518 [details] [review]:

OKay!

Comment 10 Will Thompson 2011-07-18 11:19:24 UTC

Review of attachment 45519 [details] [review]:

Yup.

Comment 11 Will Thompson 2011-07-18 11:19:54 UTC

Review of attachment 45520 [details] [review]:

++

Comment 12 Will Thompson 2011-07-18 11:20:25 UTC

Review of attachment 45521 [details] [review]:

Ship it.

Comment 13 Simon McVittie 2011-07-18 11:45:08 UTC

Thanks, fixed in git for 1.4.12, 1.5.6.

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.