As long as we are treating Autotools as a first-class citizen, what we
release will be `make distcheck` output.
Signed-off-by: Simon McVittie <smcv@collabora.com>
This adds a nice way of loading the DTD files based on the identifier
in the DOCTYPE declaration, no matter where the DTDs are installed.
See also ‘XML catalog’ Wikipedia entry and update-xmlcatalog(8).
With this parameter, docbook will generate the same id's when generating the
same docs. This is helpful to get bit-by-bit 'reproducible' output, which
makes auditing the package easier.
Tested both the cmake output and the automake output
Qt help files are used by Qt Creator and KDevelop, for example, to support
the development of Qt-based applications and libraries.
Generating api documentation in Qt help format is controlled by two
user specific options named --enable-qt-help and --with-qchdir (autotools)
and -DENABLE_QT_HELP and -DINSTALL_QCH_DIR (cmake).
This saves around 32% of the size of the archive.
[smcv: Rebased onto current master]
Signed-off-by: Simon McVittie <smcv@collabora.com>
Reviewed-by: Philip Withnall <withnall@endlessm.com>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=107630
The old version-1 format is deprecated and now produces warnings.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=106186
Reviewed-by: Philip Withnall <withnall@endlessm.com>
[smcv: Add the .devhelp2 file to .gitignore as suggested]
Signed-off-by: Simon McVittie <smcv@collabora.com>
Newer versions of yelp-build use this instead of a jQuery syntax
highlighter.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=106171
Reviewed-by: Philip Withnall <withnall@endlessm.com>
[smcv: Also add it to .gitignore as suggested]
Signed-off-by: Simon McVittie <smcv@collabora.com>
Install them to $(datadir)/xml/dbus-1, which seems to be the standard
location for installed DTDs. This means that developers can use them to
validate their introspection XML, and sysadmins can use them to validate
their bus configuration files.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=89011
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
If OS builders (distributions) have chosen to use the per-user bus,
this provides two possible modes of operation for compatibility with
existing X session startup hooks.
A legacy-free system can just upload DISPLAY, XAUTHORITY and possibly
DBUS_SESSION_BUS_ADDRESS into dbus-daemon's and systemd's activation
environments, similar to
http://cgit.freedesktop.org/systemd/systemd/tree/xorg/50-systemd-user.sh
installed by systemd (but unlike systemctl,
dbus-update-activation-environment works for traditional
D-Bus-activated services, not just for systemd services).
A system where compatibility is required for environment variables
exported by snippets in /etc/X11/xinit/xinitrc.d (in Red Hat derivatives,
Gentoo, etc.) or /etc/X11/Xsession.d (Debian derivatives) can upload
the entire environment of the X session, minus some selected environment
variables which are specific to a login session (notably XDG_SESSION_ID).
In Debian, I plan to put the former in a new dbus-user-session package
that enables a user-session-centric mode of operation for D-Bus,
and the latter in the existing dbus-x11 package, with the intention that
dbus-x11 eventually becomes a tool for change-averse setups or goes
away entirely.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=61301
Reviewed-by: Philip Withnall <philip.withnall@collabora.co.uk>
This guide gives some pointers on how to write D-Bus APIs which are nice
to use.
It adds an optional dependency on Ducktype and yelp-build from
yelp-tools. These are used when available, but are not required unless
--enable-ducktype-docs is passed to configure. They are required for
uploading the docs, however.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=88994
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
This means we no longer need man2html, which is nice.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=59805
Reviewed-by: Ralf Habacker <ralf.habacker@freenet.de>
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Building it unconditionally causes problems for minimal installations
(OSTree), and building it opportunistically means the tarball isn't
guaranteed to contain it, depending who releases libdbus and which
packages they happen to have installed at the time. If this documentation
is important enough that we need to ship it precompiled in tarballs,
we should guarantee it; or if it isn't important enough to justify that,
we should just drop it.
I don't think we really need it in the tarballs at all: most users
will get their libdbus from a binary distribution (in which case I expect
the distribution's dbus maintainers to set appropriate
build-dependencies), and those who build from source can either
install xmlto, read the documentation on our website, or at worst,
read the source XML. (We don't put the Doxygen-generated API reference
HTML in the tarball either, and I haven't heard any complaints.)
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=55426
Reviewed-by: Colin Walters <walters@verbum.org>
man2html expects to find its input on stdin, so just passing the
filename will cause it to hang waiting for input.
[man2html 1.6g as shipped in Debian seems to be fine with files on the
command line, but apparently other versions aren't? -smcv]
Signed-off-by: Jack Nagel <jacknagel@gmail.com>
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=43875
The STATIC_DOCS, DTDS and all dist_ files except XMLTO_OUTPUT are in the
source tree. The XMLTO_OUTPUT and the man2html output are in the build
tree, and the BONUS_FILES already have $(srcdir) in their names.
Also change the rules that generate the dbus-docs directory so that if
they fail, they leave behind a temporary directory, rather than leaving
behind a dbus-docs directory that causes make to not run those rules
if re-run; and change the rules to scp files to the server, to put a
trailing "/" on paths, ensuring that the tarball won't be uploaded as
"www" if the www directory doesn't already exist.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=41047
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
diagram.png and diagram.svg are linked from dbus-tutorial.html but recent
changes to doc/Makefile.am mean that if htmldir is set with configure they are
installed such that the relative link from dbus-tutorial.html does not work.
Reviewed-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
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.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=36156
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
It turns out that rsync --chmod means "pretend the source files had
already had this chmod operation applied to them", and not "chmod the
destination files" like you'd expect.
As a result, the -p (--perms) option is also needed, so that rsync will
"preserve" the modified permissions. Otherwise, the docs will not be
group-writeable as intended, and only the person who made the previous
upload will be able to upload them next time.
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=36130
Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
It's generated by configure.
Also use a more normal way to distribute man pages that are actually
source, and use man1_MANS rather than auto-detecting the section from
the man page, which is best-practice and slightly faster.
Reviewed-by: Colin Walters <walters@verbum.org>
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=34292
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'
Bug: https://bugs.freedesktop.org/show_bug.cgi?id=13495
This uploads a doc tarball, and its contents, to the appropriate
location on dbus.freedesktop.org. It also uploads the DTDs to the
appropriate location on specifications.freedesktop.org.
I believe this uploads the same files as the old update-dbus-docs.sh
script did.
This will make integrating the building of HTML versions of these
manpages into the build system way easier, at the cost of keeping
manpages in a different directory to the source for the program they
describe. I think this is an acceptable trade-off.
This depends on GNU Make for the wildcard dependency on all the source
files in dbus/. If anyone objects very strongly to this, I'd welcome
suggestions of a more portable way to do this.
