| Summary: | Please provide XSLT for generating devhelp index | ||
|---|---|---|---|
| Product: | dbus | Reporter: | Martin Pitt <martin.pitt> |
| Component: | core | Assignee: | Simon McVittie <smcv> |
| Status: | RESOLVED FIXED | QA Contact: | Rob Taylor <rob.taylor> |
| Severity: | normal | ||
| Priority: | medium | CC: | walters, will |
| Version: | unspecified | Keywords: | patch |
| Hardware: | All | ||
| OS: | All | ||
| URL: | http://git.collabora.co.uk/?p=user/smcv/dbus-smcv.git;a=shortlog;h=refs/heads/doxygenate | ||
| Whiteboard: | review+ | ||
| i915 platform: | i915 features: | ||
| Attachments: |
XSLT for doxygen to devhelp
add devhelp support and install/uninstall Generate XML from Doxygen [2/8] Add doxygen_to_devhelp.xsl (from Fedora, via Debian) [3/8] configure.in: require autoconf 2.60 [4/8] Check for xsltproc in configure.in [5/8] Use a stamp file to represent the Doxygen output [6/8] docs: use $(MKDIR_P), which we already check for in configure.in [7/8] Install the Doxygen documentation to $(htmldir) [8/8] Build dbus.devhelp using doxygen_to_devhelp.xsl and install it |
||
|
Description
Martin Pitt
2007-12-03 05:13:42 UTC
Created attachment 12912 [details]
XSLT for doxygen to devhelp
Usage:
xsltproc -o dbus.devhelp doxygen_to_devhelp.xsl doc/api/xml/index.xml
Created attachment 15572 [details] [review] add devhelp support and install/uninstall tested with "--enable-xml-doc --enable-doxygen" and "--disable-xml-doc --disable-doxygen", make install / make uninstall & make distcheck. Adding this to my to-do list: Fedora, Ubuntu, Debian and Maemo all seem to patch this, one way or another. Review of attachment 15572 [details] [review]: (This has bit-rotted a bit in the intervening 2 years, and the patch no longer applies cleanly.) ::: doc/Makefile.am @@ +33,3 @@ +install-doc: $(HTML_FILES) + @$(NORMAL_INSTALL) What does $(NORMAL_INSTALL) do? It looks like undocumented automake internals to me? @@ +58,3 @@ +# Build a DevHelp reference from the doxygen xml +$(devhelp_file): $(XML_INDEX) $(devhelp_stylesheet) + xsltproc --stringparam book_title "${PACKAGE_NAME} Reference Manual" \ configure.ac will need to check for xsltproc @@ +61,3 @@ + --stringparam book_name "${PACKAGE_NAME}" \ + --stringparam reference_prefix "../../../doc/${PACKAGE_NAME}/reference/html" \ + --stringparam docdir "../../../doc/${PACKAGE_NAME}" \ These parameters don't really make the XSLT fully generic: it still contains references to the tutorial, FAQ, spec, API reference. Nice idea, but I'm not going to commit this version right now; I'll stick with the Fedora one attached above (which we've been using for ages in Debian). @@ +64,3 @@ + -o $@ $(devhelp_stylesheet) $(XML_INDEX) + +$(HTML_INDEX) $(XML_INDEX): $(doxygen_configfile_source) $(beautify_docs_source) $(top_srcdir)/dbus/*.h What's beautify_docs_source? @@ +94,3 @@ + -rm -f $(HTML_FILES) $(devhelp_file) + -rm -rf api + -rm -f $(devhelp_file) Ignoring errors (the "-" prefix) is generally undesirable. ::: doc/doxygen_to_devhelp.xsl @@ +23,3 @@ + <sub name="API Reference" link="{$reference_prefix}/index.html"/> + </chapters> + </book> This is mis-nested: <functions> are also meant to be in the <book>. Created attachment 42022 [details] [review] Generate XML from Doxygen This is a useful input format for XSLT, for instance to make a Devhelp index. Originally from Matthias Clasen in Fedora's dbus/1.0.1-2 package, via Ubuntu, Debian and Maemo. Created attachment 42023 [details] [review] [2/8] Add doxygen_to_devhelp.xsl (from Fedora, via Debian) Originally committed by Matthias Clasen <mclasen@fedoraproject.org>. Created attachment 42024 [details] [review] [3/8] configure.in: require autoconf 2.60 We already require it in practice, for AC_PROG_MKDIR_P. It also defines $(htmldir). Created attachment 42025 [details] [review] [4/8] Check for xsltproc in configure.in Created attachment 42026 [details] [review] [5/8] Use a stamp file to represent the Doxygen output This avoids thinking it's up to date if the Doxygen build fails, but writes partial output to index.html before failing. Created attachment 42027 [details] [review] [6/8] docs: use $(MKDIR_P), which we already check for in configure.in mkdir -p isn't 100% portable, whereas $(MKDIR_P) can either be mkdir -p, install -d or (as a last resort) ./install-sh -d. Created attachment 42028 [details] [review] [7/8] Install the Doxygen documentation to $(htmldir) Use ./configure --docdir=/foo (or --htmldir=/foo) to control where it ends up. For instance, Debian could use: --docdir=/usr/share/doc/dbus-1-doc --htmldir='${docdir}/html' Created attachment 42029 [details] [review] [8/8] Build dbus.devhelp using doxygen_to_devhelp.xsl and install it These patches look good. I like devhelp. Patches applied, will be in 1.4.8 and 1.5.0. Thanks! |
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.