Added man page for bbackupquery, and updated Makefile to be able to build the man pages.

2 files changed, 359 insertions, 2 deletions

diff --git a/documentation/boxbackup/Makefile b/documentation/boxbackup/Makefile
index 36016d73..5ce67c54 100644
--- a/documentation/boxbackup/Makefile
+++ b/documentation/boxbackup/Makefile
@@ -4,11 +4,11 @@
 
 DBPROC=/usr/bin/xsltproc
 BOOKXSL=bb-book.xsl
-MANXSL=bb-man.xsl
+MANXSL= /usr/share/sgml/docbook/xsl-stylesheets/manpages/docbook.xsl
 VPATH= adminguide
 .SUFFIXES: .html .xml
 
-all: adminguide instguide 
+all: adminguide instguide manpages
 
 adminguide: adminguide/index.html 
 
@@ -24,6 +24,14 @@ instguide/index.html: instguide.xml $(BOOKXSL)
 ExceptionCodes.xml: ../../ExceptionCodes.txt
 	perl ./generate_except_xml.pl
 
+manpages: bbackupquery.html bbackupquery.1 
+
+bbackupquery.html: bbackupquery.xml
+	$(DBPROC) -o man-html/bbackupquery.html $(BOOKXSL) bbackupquery.xml
+
+bbackupquery.1: bbackupquery.xml
+	$(DBPROC) -o man-pages/bbackupquery.1 $(MANXSL) bbackupquery.xml
+
 dockit: instguide adminguide
 	tar zcf documentation-kit-0.10.tar.gz html/ instguide/ adminguide/
 
diff --git a/documentation/boxbackup/bbackupquery.xml b/documentation/boxbackup/bbackupquery.xml
new file mode 100644
index 00000000..f1b57920
--- /dev/null
+++ b/documentation/boxbackup/bbackupquery.xml
@@ -0,0 +1,349 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<refentry>
+  <refmeta>
+    <refentrytitle>bbackupquery</refentrytitle>
+
+    <manvolnum>1</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>bbackupquery</refname>
+
+    <refpurpose>Box Backup store query and retrieval</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>bbackupquery [-q] [-c configfile] [commands ...]</command>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsection>
+    <title>Description</title>
+
+    <para><literal>bbackupquery</literal> is the main way of interacting with
+    the backup store from a Box Backup client machine. It supports both
+    interactive and batch modes of operation.</para>
+
+    <para>It can be used to reviewing the status of a client machine's backup
+    store, getting status from the store server. The main use is to retrieve
+    files and directories when needed.</para>
+
+    <para><literal>bbackupquery</literal> supports interactive and batch modes
+    of operation. Interactive mode allows for interaction with the server much
+    like an interactive FTP client.</para>
+
+    <para>Batch mode is invoked by putting commands into the invocation of
+    bbackupquery. Example:</para>
+
+    <programlisting>bbackupquery "list home-dirs" quit</programlisting>
+
+    <para>Note that commands that contain spaces are enclosed in double
+    quotes. If the <literal>quit</literal> command is ommitted, after the
+    preceding commands are completed, <literal>bbackupquery</literal> will
+    enter interactive mode.</para>
+
+    <para><emphasis role="bold">Options</emphasis></para>
+
+    <para><emphasis>-q: Quiet. Suppresses status output while
+    running.</emphasis></para>
+
+    <para><emphasis>-c configfile: Use config file, instead of the default
+    bbackupd.conf file. Can be a relative or full path.</emphasis></para>
+
+    <refsection>
+      <title>Commands</title>
+
+      <para>The commands that can be used in <literal>bbackupquery</literal>
+      are listed below.</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><literal>help</literal></para>
+
+          <para>Displays the basic help message, which gives information about
+          the commands available in bbackupquery. Use the form <literal>help
+          command</literal>, to get help on a specific command.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>quit</literal></para>
+
+          <para>End the session with the store server, and quit
+          <literal>bbackupquery</literal>.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>cd [options] &lt;directory-name&gt;</literal></para>
+
+          <para>Change directory. Options:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>-d</literal> -- consider deleted directories for
+              traversal</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-o</literal> -- consider old versions of
+              directories for traversal. This option should never be useful in
+              a correctly formed store.</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para><literal>lcd &lt;local-directory-name&gt;</literal></para>
+
+          <para>Change directory on the client machine. To list the contents
+          of the local directory, type <literal>sh ls</literal> (on unix-like
+          machines). TODO: Does <literal>sh dir</literal> work on
+          Windows?</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>list [options] [directory-name]</literal></para>
+
+          <para>The <literal>list</literal> (or its synonym
+          <literal>ls</literal>) command lists the content of the current, or
+          specified, directory. The options are as follows:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>-r</literal> -- recursively list all files</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-d</literal> -- list deleted files and
+              directories</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-o</literal> -- list old versions of files and
+              directories</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-I</literal> -- don't display object IDs</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-F</literal> -- don't display flags</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-t</literal> -- show file modification time (and
+              attr mod time, if the object has attributes.</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-s</literal> -- show file size in blocks used on
+              server. Note that this is only a very approximate indication of
+              local file size.</para>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para><literal>ls [options] [directory-name]</literal></para>
+
+          <para>Synonym for <literal>list</literal>.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal><literal>pwd</literal></literal></para>
+
+          <para>Print current directory, always relative to the backup store
+          root.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>sh &lt;shell command&gt;</literal></para>
+
+          <para>Everything after the sh is passed to a shell and run. All
+          output from the command is displayed in the client.</para>
+
+          <para>Example: to list the contents of the current directory on the
+          client machine type <literal>sh ls</literal>.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>compare -a</literal></para>
+
+          <para><literal>compare -l &lt;location-name&gt;</literal></para>
+
+          <para><literal>compare &lt;store-dir-name&gt;
+          &lt;local-dir-name&gt;</literal></para>
+
+          <para>Compare the current data in the store with the data on the
+          disc. Please note that all the data will be downloaded from the
+          store, so this can be a very lengthy process depending on the size
+          of the store, and the size of the part you are comparing.</para>
+
+          <para>Options:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>-a</literal> -- compare all locations. </para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-l</literal> -- compare one backup location as
+              specified in the configuration file. This compares one of the
+              top level store directories.</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-c</literal> -- set return code. The return code
+              is set to the following values, if <literal>quit</literal> is
+              the next command. So, if another command is run after the
+              <literal>compare</literal>, the return code will not refer to
+              the <literal>compare</literal>. This option is very useful for
+              automating compares. Return code values:</para>
+
+              <itemizedlist>
+                <listitem>
+                  <para>1 -- no differences were found</para>
+                </listitem>
+
+                <listitem>
+                  <para>2 -- differences were found</para>
+                </listitem>
+
+                <listitem>
+                  <para>3 -- an error occured</para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </itemizedlist>
+        </listitem>
+
+        <listitem>
+          <para><literal>get &lt;object-filename&gt;
+          [&lt;local-filename&gt;]</literal></para>
+
+          <para><literal>get -i &lt;object-id&gt;
+          &lt;local-filename&gt;</literal></para>
+
+          <para>Gets a file from the store. Object is specified as the
+          filename within the current directory. Local filename is optional.
+          Ignores old and deleted files when searching the directory for the
+          file to retrieve.</para>
+
+          <para>To get an old or deleted file, use the <literal>-i</literal>
+          option and select the object as a hex object ID (first column in
+          listing). The local filename must be specified.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>getobject &lt;object-id&gt;
+          &lt;local-filename&gt;</literal></para>
+
+          <para>Gets the object specified by the object id (in hex) and stores
+          the raw contents in the local file specified. <emphasis
+          role="bold">Note</emphasis>: This is only useful for debugging as it
+          does not decode files from the stored format, which is encrypted and
+          compressed.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>restore [-d] &lt;directory-name&gt;
+          &lt;local-directory-name&gt;</literal></para>
+
+          <para><literal>restore -r</literal></para>
+
+          <para>Restores a directory to the local disc. The local directory
+          specified must not exist (unless a previous restore is being
+          restarted). The root cannot be restored -- restore locations
+          individually. </para>
+
+          <para>Options:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>-d</literal> -- restore a deleted
+              directory</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>-r</literal> -- resume an interrupted
+              restore</para>
+            </listitem>
+          </itemizedlist>
+
+          <para> If a restore operation is interrupted for any reason, it can
+          be restarted using the <literal>-r</literal> switch. Restore
+          progress information is saved in a file at regular intervals during
+          the restore operation to allow restarts.</para>
+        </listitem>
+
+        <listitem>
+          <para>usage</para>
+
+          <para>Show space used on the server for this account. Display
+          fields:</para>
+
+          <itemizedlist>
+            <listitem>
+              <para><literal>Used</literal>: Total amount of space used on the
+              server</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>Old files</literal>: Space used by old
+              files</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>Deleted files</literal>: Space used by deleted
+              files</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>Directories</literal>: Space used by the
+              directory structure</para>
+            </listitem>
+          </itemizedlist>
+
+          <para>When Used exceeds the soft limit, the server will start to
+          remove old and deleted files until the usage drops below the soft
+          limit. After a while, you should expect to see the usage stay at
+          just below the soft limit. You only need more space if the space
+          used by old and deleted files is near zero.</para>
+        </listitem>
+      </itemizedlist>
+    </refsection>
+  </refsection>
+
+  <refsection>
+    <title>Author</title>
+
+    <para>Ben Summers and contributors. For help, please go to the <ulink
+    url="http://boxbackup.hostworks.ca/">Wiki</ulink>, or subscribe to the Box
+    Backup <ulink
+    url="http://lists.warhead.org.uk/mailman/listinfo/boxbackup">mailing
+    list.</ulink></para>
+  </refsection>
+
+  <refsection>
+    <title>See Also</title>
+
+    <para>bbackupd.conf(8)</para>
+  </refsection>
+
+  <refsection>
+    <title>Files</title>
+
+    <para><literal>bbackupquery</literal> uses the Box Backup client
+    configuration file, usually located in
+    <filename>/etc/box/bbackupd.conf</filename>. On Windows this file is
+    usually located in the installation directory, and is named
+    <filename>bbackupd.conf</filename> as well.</para>
+  </refsection>
+
+  <refsection>
+    <title>Bugs</title>
+
+    <para>TODO: get known bugs for 0.10 in here.</para>
+  </refsection>
+</refentry>
\ No newline at end of file