Merge branch 'documentation-build-system'

6 files changed, 1 insertions, 490 deletions

diff --git a/tools/Makefile.am b/tools/Makefile.am
index 271c1508..ce88c85f 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -48,8 +48,7 @@ dbus_uuidgen_LDFLAGS=@R_DYNAMIC_LDFLAG@
 dbus_launch_LDADD= $(DBUS_X_LIBS) $(DBUS_CLIENT_LIBS)
 dbus_launch_LDFLAGS=@R_DYNAMIC_LDFLAG@
 
-man_MANS = dbus-send.1 dbus-monitor.1 dbus-launch.1 dbus-cleanup-sockets.1 dbus-uuidgen.1
-EXTRA_DIST = $(man_MANS) run-with-tmp-session-bus.sh strtoll.c strtoull.c
+EXTRA_DIST = run-with-tmp-session-bus.sh strtoll.c strtoull.c
 CLEANFILES = 				\
 	run-with-tmp-session-bus.conf
 
diff --git a/tools/dbus-cleanup-sockets.1 b/tools/dbus-cleanup-sockets.1
deleted file mode 100644
index ca669f49..00000000
--- a/tools/dbus-cleanup-sockets.1
+++ /dev/null
@@ -1,43 +0,0 @@
-.\" 
-.\" dbus-cleanup-sockets manual page.
-.\" Copyright (C) 2003 Red Hat, Inc.
-.\"
-.TH dbus-cleanup-sockets 1
-.SH NAME
-dbus-cleanup-sockets \- clean up leftover sockets in a directory
-.SH SYNOPSIS
-.PP
-.B dbus-cleanup-sockets [DIRECTORY]
-
-.SH DESCRIPTION
-
-The \fIdbus-cleanup-sockets\fP command cleans up unused D-Bus
-connection sockets. See http://www.freedesktop.org/software/dbus/ for
-more information about the big picture.
-
-.PP
-If given no arguments, \fIdbus-cleanup-sockets\fP cleans up sockets 
-in the standard default socket directory for the
-per-user-login-session message bus; this is usually /tmp. 
-Optionally, you can pass a different directory on the command line.
-
-.PP
-On Linux, this program is essentially useless, because D-Bus defaults
-to using "abstract sockets" that exist only in memory and don't have a
-corresponding file in /tmp. 
-
-.PP
-On most other flavors of UNIX, it's possible for the socket files to
-leak when programs using D-Bus exit abnormally or without closing
-their D-Bus connections. Thus, it might be interesting to run
-dbus-cleanup-sockets in a cron job to mop up any leaked sockets.
-Or you can just ignore the leaked sockets, they aren't really hurting
-anything, other than cluttering the output of "ls /tmp"
-
-.SH AUTHOR
-dbus-cleanup-sockets was adapted by Havoc Pennington from
-linc-cleanup-sockets written by Michael Meeks.
-
-.SH BUGS
-Please send bug reports to the D-Bus mailing list or bug tracker,
-see http://www.freedesktop.org/software/dbus/
diff --git a/tools/dbus-launch.1 b/tools/dbus-launch.1
deleted file mode 100644
index 0ea19495..00000000
--- a/tools/dbus-launch.1
+++ /dev/null
@@ -1,183 +0,0 @@
-.\" 
-.\" dbus-launch manual page.
-.\" Copyright (C) 2003 Red Hat, Inc.
-.\"
-.TH dbus-launch 1
-.SH NAME
-dbus-launch \- Utility to start a message bus from a shell script
-.SH SYNOPSIS
-.PP
-.B dbus-launch [\-\-version] [\-\-sh-syntax] [\-\-csh-syntax] [\-\-auto-syntax] [\-\-exit-with-session] [\-\-autolaunch=MACHINEID] [\-\-config-file=FILENAME] [PROGRAM] [ARGS...]
-
-.SH DESCRIPTION
-
-The \fIdbus-launch\fP command is used to start a session bus 
-instance of \fIdbus-daemon\fP from a shell script.
-It would normally be called from a user's login
-scripts. Unlike the daemon itself, \fIdbus-launch\fP exits, so
-backticks or the $() construct can be used to read information from
-\fIdbus-launch\fP.
-
-With no arguments, \fIdbus-launch\fP will launch a session bus
-instance and print the address and pid of that instance to standard
-output.
-
-You may specify a program to be run; in this case, \fIdbus-launch\fP
-will launch a session bus instance, set the appropriate environment
-variables so the specified program can find the bus, and then execute the
-specified program, with the specified arguments.  See below for
-examples.
-
-If you launch a program, \fIdbus-launch\fP will not print the
-information about the new bus to standard output.
-
-When \fIdbus-launch\fP prints bus information to standard output, by
-default it is in a simple key-value pairs format. However, you may 
-request several alternate syntaxes using the \-\-sh-syntax, \-\-csh-syntax,
-\-\-binary-syntax, or
-\-\-auto-syntax options. Several of these cause \fIdbus-launch\fP to emit shell code
-to set up the environment.
-
-With the \-\-auto-syntax option, \fIdbus-launch\fP looks at the value
-of the SHELL environment variable to determine which shell syntax
-should be used.  If SHELL ends in "csh", then csh-compatible code is
-emitted; otherwise Bourne shell code is emitted.  Instead of passing
-\-\-auto-syntax, you may explicity specify a particular one by using
-\-\-sh-syntax for Bourne syntax, or \-\-csh-syntax for csh syntax.
-In scripts, it's more robust to avoid \-\-auto-syntax and you hopefully
-know which shell your script is written in.
-
-.PP
-See http://www.freedesktop.org/software/dbus/ for more information
-about D-Bus. See also the man page for \fIdbus-daemon\fP.
-
-.PP
-Here is an example of how to use \fIdbus-launch\fP with an 
-sh-compatible shell to start the per-session bus daemon:
-.nf
-
-  ## test for an existing bus daemon, just to be safe
-  if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
-      ## if not found, launch a new one
-      eval `dbus-launch --sh-syntax --exit-with-session`
-      echo "D-Bus per-session daemon address is: $DBUS_SESSION_BUS_ADDRESS"
-  fi
-
-.fi
-You might run something like that in your login scripts.
-
-.PP
-Another way to use \fIdbus-launch\fP is to run your main session
-program, like so:
-.nf
-
-dbus-launch gnome-session
-
-.fi
-The above would likely be appropriate for ~/.xsession or ~/.Xclients.
-
-.SH AUTOMATIC LAUNCHING
-
-.PP
-If DBUS_SESSION_BUS_ADDRESS is not set for a process that tries to use
-D-Bus, by default the process will attempt to invoke dbus-launch with
-the --autolaunch option to start up a new session bus or find the 
-existing bus address on the X display or in a file in
-~/.dbus/session-bus/
-
-.PP
-Whenever an autolaunch occurs, the application that had to
-start a new bus will be in its own little world; it can effectively
-end up starting a whole new session if it tries to use a lot of 
-bus services. This can be suboptimal or even totally broken, depending
-on the app and what it tries to do.
-
-.PP
-There are two common reasons for autolaunch. One is ssh to a remote
-machine. The ideal fix for that would be forwarding of
-DBUS_SESSION_BUS_ADDRESS in the same way that DISPLAY is forwarded.
-In the meantime, you can edit the session.conf config file to 
-have your session bus listen on TCP, and manually set
-DBUS_SESSION_BUS_ADDRESS, if you like.
-
-.PP
-The second common reason for autolaunch is an su to another user, and
-display of X applications running as the second user on the display
-belonging to the first user. Perhaps the ideal fix in this case
-would be to allow the second user to connect to the session bus of the
-first user, just as they can connect to the first user's display.
-However, a mechanism for that has not been coded.
-
-.PP
-You can always avoid autolaunch by manually setting
-DBUS_SESSION_BUS_ADDRESS. Autolaunch happens because the default
-address if none is set is "autolaunch:", so if any other address is
-set there will be no autolaunch. You can however include autolaunch in
-an explicit session bus address as a fallback, for example
-DBUS_SESSION_BUS_ADDRESS="something:,autolaunch:" - in that case if
-the first address doesn't work, processes will autolaunch. (The bus
-address variable contains a comma-separated list of addresses to try.)
-
-.PP
-The --autolaunch option is considered an internal implementation
-detail of libdbus, and in fact there are plans to change it. There's
-no real reason to use it outside of the libdbus implementation anyhow.
-
-.SH OPTIONS
-The following options are supported:
-.TP
-.I "--auto-syntax"
-Choose \-\-csh-syntax or \-\-sh-syntax based on the SHELL environment variable.
-
-.I "--binary-syntax"
-Write to stdout a nul-terminated bus address, then the bus PID as a
-binary integer of size sizeof(pid_t), then the bus X window ID as a
-binary integer of size sizeof(long). Integers are in the machine's
-byte order, not network byte order or any other canonical byte order.
-
-.TP
-.I "--close-stderr"
-Close the standard error output stream before starting the D-Bus
-daemon. This is useful if you want to capture dbus-launch error
-messages but you don't want dbus-daemon to keep the stream open to
-your application.
-
-.TP
-.I "--config-file=FILENAME"
-Pass \-\-config-file=FILENAME to the bus daemon, instead of passing it 
-the \-\-session argument. See the man page for dbus-daemon
-
-.TP
-.I "--csh-syntax"
-Emit csh compatible code to set up environment variables.
-
-.TP
-.I "--exit-with-session"
-If this option is provided, a persistent "babysitter" process will be 
-created that watches stdin for HUP and tries to connect to the X
-server. If this process gets a HUP on stdin or loses its X connection,
-it kills the message bus daemon.
-
-.TP
-.I "--autolaunch=MACHINEID"
-This option implies that \fIdbus-launch\fP should scan for a
-previously-started session and reuse the values found there. If no
-session is found, it will start a new session. The
-\-\-exit-with-session option is implied if \-\-autolaunch is given.
-This option is for the exclusive use of libdbus, you do not want to
-use it manually. It may change in the future.
-
-.TP
-.I "--sh-syntax"
-Emit Bourne-shell compatible code to set up environment variables.
-
-.TP
-.I "--version"
-Print the version of dbus-launch
-
-.SH AUTHOR
-See http://www.freedesktop.org/software/dbus/doc/AUTHORS
-
-.SH BUGS
-Please send bug reports to the D-Bus mailing list or bug tracker,
-see http://www.freedesktop.org/software/dbus/
diff --git a/tools/dbus-monitor.1 b/tools/dbus-monitor.1
deleted file mode 100644
index c24c14d9..00000000
--- a/tools/dbus-monitor.1
+++ /dev/null
@@ -1,78 +0,0 @@
-.\" 
-.\" dbus-monitor manual page.
-.\" Copyright (C) 2003 Red Hat, Inc.
-.\"
-.TH dbus-monitor 1
-.SH NAME
-dbus-monitor \- debug probe to print message bus messages
-.SH SYNOPSIS
-.PP
-.B dbus-monitor
-[\-\-system | \-\-session | \-\-address ADDRESS] [\-\-profile | \-\-monitor]
-[watch expressions]
-
-.SH DESCRIPTION
-
-The \fIdbus-monitor\fP command is used to monitor messages going
-through a D-Bus message bus.  See
-http://www.freedesktop.org/software/dbus/ for more information about
-the big picture.
-
-.PP
-There are two well-known message buses: the systemwide message bus
-(installed on many systems as the "messagebus" service) and the
-per-user-login-session message bus (started each time a user logs in).
-The \-\-system and \-\-session options direct \fIdbus-monitor\fP to
-monitor the system or session buses respectively.  If neither is
-specified, \fIdbus-monitor\fP monitors the session bus.
-
-.PP
-\fIdbus-monitor\fP has two different output modes, the 'classic'-style
-monitoring mode and profiling mode. The profiling format is a compact
-format with a single line per message and microsecond-resolution timing
-information. The \-\-profile and \-\-monitor options select the profiling
-and monitoring output format respectively. If neither is specified,
-\fIdbus-monitor\fP uses the monitoring output format.
-
-.PP
-In order to get \fIdbus-monitor\fP to see the messages you are interested
-in, you should specify a set of watch expressions as you would expect to
-be passed to the \fIdbus_bus_add_match\fP function.
-
-.PP 
-The message bus configuration may keep \fIdbus-monitor\fP from seeing
-all messages, especially if you run the monitor as a non-root user.
-
-.SH OPTIONS
-.TP
-.I "--system"
-Monitor the system message bus.
-.TP
-.I "--session"
-Monitor the session message bus.  (This is the default.)
-.TP
-.I "--address ADDRESS"
-Monitor an arbitrary message bus given at ADDRESS.
-.TP
-.I "--profile"
-Use the profiling output format.
-.TP
-.I "--monitor"
-Use the monitoring output format.  (This is the default.)
-
-.SH EXAMPLE
-Here is an example of using dbus-monitor to watch for the gnome typing
-monitor to say things
-.nf
-
-  dbus-monitor "type='signal',sender='org.gnome.TypingMonitor',interface='org.gnome.TypingMonitor'"
-
-.fi
-
-.SH AUTHOR
-dbus-monitor was written by Philip Blundell.
-The profiling output mode was added by Olli Salli.
-
-.SH BUGS
-Please send bug reports to the D-Bus mailing list or bug tracker,
-see http://www.freedesktop.org/software/dbus/
diff --git a/tools/dbus-send.1 b/tools/dbus-send.1
deleted file mode 100644
index 4878c3d9..00000000
--- a/tools/dbus-send.1
+++ /dev/null
@@ -1,95 +0,0 @@
-.\" 
-.\" dbus-send manual page.
-.\" Copyright (C) 2003 Red Hat, Inc.
-.\"
-.TH dbus-send 1
-.SH NAME
-dbus-send \- Send a message to a message bus
-.SH SYNOPSIS
-.PP
-.B dbus-send
-[\-\-system | \-\-session] [\-\-dest=NAME] [\-\-print-reply]
-[\-\-type=TYPE] <destination object path> <message name> [contents ...]
-
-.SH DESCRIPTION
-
-The \fIdbus-send\fP command is used to send a message to a D-Bus message
-bus. See http://www.freedesktop.org/software/dbus/ for more 
-information about the big picture.
-
-.PP
-There are two well-known message buses: the systemwide message bus 
-(installed on many systems as the "messagebus" service) and the 
-per-user-login-session message bus (started each time a user logs in).
-The \-\-system and \-\-session options direct \fIdbus-send\fP to send
-messages to the system or session buses respectively.  If neither is
-specified, \fIdbus-send\fP sends to the session bus.
-
-.PP 
-Nearly all uses of \fIdbus-send\fP must provide the \-\-dest argument
-which is the name of a connection on the bus to send the message to. If
-\-\-dest is omitted, no destination is set.
-
-.PP
-The object path and the name of the message to send must always be
-specified. Following arguments, if any, are the message contents
-(message arguments).  These are given as type-specified values and 
-may include containers (arrays, dicts, and variants) as described below.
-
-.nf
-<contents>   ::= <item> | <container> [ <item> | <container>...]
-<item>       ::= <type>:<value>
-<container>  ::= <array> | <dict> | <variant>
-<array>      ::= array:<type>:<value>[,<value>...] 
-<dict>       ::= dict:<type>:<type>:<key>,<value>[,<key>,<value>...]
-<variant>    ::= variant:<type>:<value>
-<type>       ::= string | int16 | uint 16 | int32 | uint32 | int64 | uint64 | double | byte | boolean | objpath
-.fi
-
-D-Bus supports more types than these, but \fIdbus-send\fP currently
-does not.  Also, \fIdbus-send\fP does not permit empty containers
-or nested containers (e.g. arrays of variants).
-
-.PP
-Here is an example invocation:
-.nf
-
-  dbus-send \-\-dest=org.freedesktop.ExampleName               \\
-            /org/freedesktop/sample/object/name              \\
-            org.freedesktop.ExampleInterface.ExampleMethod   \\
-            int32:47 string:'hello world' double:65.32       \\
-            array:string:"1st item","next item","last item"  \\
-            dict:string:int32:"one",1,"two",2,"three",3      \\
-            variant:int32:-8                                 \\
-            objpath:/org/freedesktop/sample/object/name 
-
-.fi
-
-Note that the interface is separated from a method or signal 
-name by a dot, though in the actual protocol the interface
-and the interface member are separate fields.
-
-.SH OPTIONS
-The following options are supported:
-.TP
-.I "--dest=NAME"
-Specify the name of the connection to receive the message.
-.TP
-.I "--print-reply"
-Block for a reply to the message sent, and print any reply received.
-.TP
-.I "--system"
-Send to the system message bus.
-.TP
-.I "--session"
-Send to the session message bus.  (This is the default.)
-.TP
-.I "--type=TYPE"
-Specify "method_call" or "signal" (defaults to "signal").
-
-.SH AUTHOR
-dbus-send was written by Philip Blundell.
-
-.SH BUGS
-Please send bug reports to the D-Bus mailing list or bug tracker,
-see http://www.freedesktop.org/software/dbus/
diff --git a/tools/dbus-uuidgen.1 b/tools/dbus-uuidgen.1
deleted file mode 100644
index 480fd18f..00000000
--- a/tools/dbus-uuidgen.1
+++ /dev/null
@@ -1,89 +0,0 @@
-.\" 
-.\" dbus-uuidgen manual page.
-.\" Copyright (C) 2006 Red Hat, Inc.
-.\"
-.TH dbus-uuidgen 1
-.SH NAME
-dbus-uuidgen \- Utility to generate UUIDs
-.SH SYNOPSIS
-.PP
-.B dbus-uuidgen [\-\-version] [\-\-ensure[=FILENAME]] [\-\-get[=FILENAME]]
-
-.SH DESCRIPTION
-
-The \fIdbus-uuidgen\fP command generates or reads a universally unique ID.
-
-.PP
-Note that the D-Bus UUID has no relationship to RFC 4122 and does not generate
-UUIDs compatible with that spec. Many systems have a separate command
-for that (often called "uuidgen").
-
-.PP
-See http://www.freedesktop.org/software/dbus/ for more information
-about D-Bus.
-
-.PP
-The primary usage of \fIdbus-uuidgen\fP is to run in the post-install
-script of a D-Bus package like this:
-.nf
-  dbus-uuidgen --ensure
-.fi
-
-.PP
-This will ensure that /var/lib/dbus/machine-id exists and has the uuid in it.
-It won't overwrite an existing uuid, since this id should remain fixed
-for a single machine until the next reboot at least.
-
-.PP
-The important properties of the machine UUID are that 1) it remains
-unchanged until the next reboot and 2) it is different for any two 
-running instances of the OS kernel. That is, if two processes see the 
-same UUID, they should also see the same shared memory, UNIX domain
-sockets, local X displays, localhost.localdomain resolution, process
-IDs, and so forth.
-
-.PP
-If you run \fIdbus-uuidgen\fP with no options it just prints a new uuid made
-up out of thin air.
-
-.PP
-If you run it with --get, it prints the machine UUID by default, or
-the UUID in the specified file if you specify a file.
-
-.PP
-If you try to change an existing machine-id on a running system, it will
-probably result in bad things happening. Don't try to change this file. Also,
-don't make it the same on two different systems; it needs to be different
-anytime there are two different kernels running.
-
-.PP
-The UUID should be different on two different virtual machines,
-because there are two different kernels.
-
-.SH OPTIONS
-The following options are supported:
-.TP
-.I "--get[=FILENAME]"
-If a filename is not given, defaults to localstatedir/lib/dbus/machine-id
-(localstatedir is usually /var). If this file exists and is valid, the
-uuid in the file is printed on stdout. Otherwise, the command exits 
-with a nonzero status.
-
-.TP
-.I "--ensure[=FILENAME]"
-If a filename is not given, defaults to localstatedir/lib/dbus/machine-id
-(localstatedir is usually /var). If this file exists then it will be
-validated, and a failure code returned if it contains the wrong thing.
-If the file does not exist, it will be created with a new uuid in it.
-On success, prints no output.
-
-.TP
-.I "--version"
-Print the version of dbus-uuidgen
-
-.SH AUTHOR
-See http://www.freedesktop.org/software/dbus/doc/AUTHORS
-
-.SH BUGS
-Please send bug reports to the D-Bus mailing list or bug tracker,
-see http://www.freedesktop.org/software/dbus/