[kde-doc-english] [akonadiclient] doc: Migrate RST documentation to DocBook
Bhaskar Kandiyal
bkandiyal at gmail.com
Mon Aug 18 07:00:58 UTC 2014
Git commit fed08467f29f15f88fb6e4791eb88d0f5febd374 by Bhaskar Kandiyal.
Committed on 18/08/2014 at 07:00.
Pushed by bkandiyal into branch 'master'.
Migrate RST documentation to DocBook
REVIEW: 119811
M +1 -18 doc/CMakeLists.txt
D +0 -285 doc/akonadiclient.1.rst
A +412 -0 doc/man-akonadiclient.1.docbook
http://commits.kde.org/akonadiclient/fed08467f29f15f88fb6e4791eb88d0f5febd374
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index f28ff08..c8183c8 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -1,18 +1 @@
-set(AKONADICLIENTDOC_MANS
- akonadiclient.1
-)
-
-find_program(RST2MAN_EXECUTABLE NAMES rst2man)
-find_program(GZIP_EXECUTABLE NAMES gzip)
-
-foreach(manpage ${AKONADICLIENTDOC_MANS})
- execute_process(COMMAND ${RST2MAN_EXECUTABLE}
- ${CMAKE_CURRENT_SOURCE_DIR}/${manpage}.rst
- ${CMAKE_CURRENT_BINARY_DIR}/${manpage}
- )
-
- execute_process(COMMAND ${GZIP_EXECUTABLE} -f ${CMAKE_CURRENT_BINARY_DIR}/${manpage})
-
-endforeach()
-
-install(FILES ${CMAKE_CURRENT_BINARY_DIR}/akonadiclient.1.gz DESTINATION ${MAN_INSTALL_DIR}/man1/)
+kde4_create_manpage(man-akonadiclient.1.docbook 1 INSTALL_DESTINATION ${MAN_INSTALL_DIR})
diff --git a/doc/akonadiclient.1.rst b/doc/akonadiclient.1.rst
deleted file mode 100644
index bef495e..0000000
--- a/doc/akonadiclient.1.rst
+++ /dev/null
@@ -1,285 +0,0 @@
-==============
-akonadiclient
-==============
---------------------------------
-A commandline client for Akonadi
---------------------------------
-
-:Author: Bhaskar Kandiyal <bkandiyal at gmail.com>
-:Date: August 12 2014
-:Copyright: Copyright (C) 2014 Bhaskar Kandiyal. Free use of this software is granted under the terms of the GNU General Public License version 2 or any later version.
-:Version: 0.1
-:Manual section: 1
-
-SYNOPSIS
-========
-**akonadiclient** command [options] [arguments]
-
-DESCRIPTION
-===========
-**akonadiclient** is a commandline client for manipulating KDE's Akonadi datastore. It provides an easy way to manipulate Akonadi's data through the commandline.
-For example, adding items, collections, renaming or moving collections and also controlling the Akonadi agents.
-
-COMMANDS
-========
-
-Filesystem Commands
--------------------
-
-**copy**
-
- akonadiclient copy [OPTIONS] SOURCE DESTINATION
-
- Used to copy collections or items from one collection to another.
-
- Options:
-
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-**create**
-
- akonadiclient create OPTIONS COLLECTION
-
- Creates a new collection. Please note that top-level collections can only be created by an Akonadi resource.
-
- Options:
-
- **-p, --parent <collection>**
-
- Parent collection to create the new collection in.
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-**delete**
-
- akonadiclient delete [OPTIONS] COLLECTION | ITEM
-
- Delete a collection or an item.
-
- Options:
-
- **-c, --collection**
-
- Assume that a collection is specified as an argument
-
- **-i, --item**
-
- Assume that an item is specified as an argument
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-**list**
-
- akonadiclient list [OPTIONS] COLLECTION
-
- List sub-collections and / or items inside the collection specified by COLLECTION.
-
- Options:
-
- **-l, --details**
-
- List more detailed information
-
- **-c, --collections**
-
- List only sub-collections
-
- **-i, --items**
-
- List only contained items
-
-**move**
-
- akonadiclient move [OPTIONS] SOURCE DESTINATION
-
- Move collections or items into another collection
-
- Options:
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-**rename**
-
- akonadiclient rename [OPTIONS] COLLECTION NAME
-
- Renames a the specified collection to NAME
-
- Options:
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-Data Commands
--------------
-
-**add**
-
- akonadiclient add [OPTIONS] COLLECTION FILES
-
- Add items to a specified collection
-
-
- Options:
-
- **-b, --base <dir>**
-
- Base directory for input files / directories, default is current
-
- **-f, --flat**
-
- Flat mode, do not duplicate subdirectory structure
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-
-**edit**
-
-
- akonadiclient edit [OPTIONS] ITEM
-
- Opens up the payload of ITEM in a text editor specified by the environment variable $EDITOR
-
- Options:
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-**expand**
-
-
- akonadiclient expand [OPTIONS] ITEM
-
- Expand a contact group item
-
- Options:
-
- **-b, --brief**
-
- Brief output (email addresses only)
-
-**export**
-
-
- akonadiclient export [OPTIONS] COLLECTION FILE
-
- Exports COLLECTION to an XML file specified by FILE
-
- Options:
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-**import**
-
- akonadiclient import [OPTIONS] PARENT FILE
-
- Imports an XML file inside the collection specified by PARENT. If the collection already exists, it's contents are merged with the contents of the collection in the XML file.
-
- Options:
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-**info**
-
- akonadiclient info [OPTIONS] COLLECTION | ITEM
-
- Show full information about a collection or item
-
- Options:
-
- **-c, --collection**
-
- Assume that a collection is specified
-
- **-i, --item**
-
- Assume that an item is specified
-
-**show**
-
- akonadiclient show ITEM
-
- Show the raw payload of an item
-
-
-**tags**
-
- akonadiclient tags [OPTIONS]
-
- List all known tags
-
- Options:
-
- **-b, --brief**
-
- Brief output - tag names only
-
- **-u, --urls**
-
- Brief output - tag URLs only
-
-**update**
-
- akonadiclient update ITEM FILE
-
- Updates the raw payload of an item specified by ITEM with the contents of FILE
-
- Options:
-
- **-n, --dryrun**
-
- Run without making any actual changes
-
-Miscellaneous Commands
-----------------------
-
-**agents**
-
- akonadiclient agents OPTIONS [AGENTS...]
-
- Allows managing of Akonadi agents like changing the state of an agent, restarting an agent or listing all agents and thier state.
-
- Options:
-
- **-l, --list**
-
- List all agents
-
- **-s, --setstate <state>**
-
- Set <state> for specified agents. Valid states are "online" and "offline".
-
- **-g, --getstate**
-
- Get state for the specified agents
-
- **-i, --info**
- Shows information about the specified agents
-
- **-r, --restart**
- Restarts the specified agents
-
- **-n, --dryrun**
- Run without making any actual changes
-
-**help**
-
- akonadiclient help [COMMAND]
-
- Displays help for COMMAND. If COMMAND is not specified then it lists all the available commands.
diff --git a/doc/man-akonadiclient.1.docbook b/doc/man-akonadiclient.1.docbook
new file mode 100644
index 0000000..dd45dd9
--- /dev/null
+++ b/doc/man-akonadiclient.1.docbook
@@ -0,0 +1,412 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+<title>akonadiclient man page</title>
+<author><personname>
+<firstname>Bhaskar</firstname>
+<surname>Kandiyal</surname>
+</personname>
+<email>bkandiyal at gmail.com</email></author>
+<date>2014-08-17</date>
+<productname>AkonadiClient</productname>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>akonadiclient</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>akonadiclient</command></refname>
+<refpurpose>A commandline client for Akonadi</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>akonadiclient</command>
+<arg choice="opt">command</arg>
+<arg choice="opt">--help</arg>
+<arg choice="opt">--version</arg>
+<arg choice="opt">&kde; Generic Options</arg>
+<arg choice="opt">Qt Generic Options</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+<para>akonadiclient is a commandline client for manipulating KDE's Akonadi datastore. It provides an easy way to manipulate Akonadi's data through the commandline.
+For example, adding items, collections, renaming or moving collections and also controlling the Akonadi agents.</para>
+
+</refsect1>
+
+<refsect1>
+<title>Commands</title>
+ <refsect2>
+ <title>Filesystem Commands</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>copy</option></term>
+ <listitem>
+ <para>akonadiclient copy [OPTIONS] SOURCE DESTINATION</para>
+ <para>Used to copy collections or items from one collection to another.</para>
+ <para>Options:</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>create</option></term>
+ <listitem>
+ <para>akonadiclient create [OPTIONS] COLLECTION</para>
+ <para>Creates a new collection. Please note that top-level collections can only be created by an Akonadi resource.</para>
+ <para>Options:</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-p, --parent <replaceable>collection</replaceable></option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>delete</option></term>
+ <listitem>
+ <para>akonadiclient delete [OPTIONS] COLLECTION | ITEM</para>
+ <para>Deletes a collection or an item.</para>
+ <para>Options:</para>
+ <variablelist>
+ <varlistentry>
+ <term><option>-c, --collection</option></term>
+ <listitem><para>Assume that a collection is specified as an argument</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-i, --item</option></term>
+ <listitem><para>Assume that an item is specified as an argument</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>list</option></term>
+ <listitem>
+ <para>akonadiclient list [OPTIONS] COLLECTION</para>
+ <para>Deletes a collection or an item.</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-l, --details</option></term>
+ <listitem><para>List more detailed information</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-c, --collections</option></term>
+ <listitem><para>List only sub-collections</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-i, --items</option></term>
+ <listitem><para>List only contained items</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>move</option></term>
+ <listitem>
+ <para>akonadiclient move [OPTIONS] SOURCE DESTINATION</para>
+ <para>Move collections or items into another collection.</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>rename</option></term>
+ <listitem>
+ <para>akonadiclient rename [OPTIONS] COLLECTION NAME</para>
+ <para>Renames a specified collection to NAME</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Data Commands</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>add</option></term>
+ <listitem>
+ <para>akonadiclient add [OPTIONS] COLLECTION FILES</para>
+ <para>Add items to a specified collection</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-b, --base <replaceable>dir</replaceable></option></term>
+ <listitem><para>Base directory for input files / directories, default is current</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-f, --flat</option></term>
+ <listitem><para>Flat mode, do not duplicate subdirectory structure</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>edit</option></term>
+ <listitem>
+ <para>akonadiclient edit [OPTIONS] ITEM</para>
+ <para>Opens the payload of ITEM in a text editor specified by the environment variable $EDITOR</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>expand</option></term>
+ <listitem>
+ <para>akonadiclient expand [OPTIONS] ITEM</para>
+ <para>Expands a contact group item</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-b, --brief</option></term>
+ <listitem><para>Brief output (email addresses only)</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>export</option></term>
+ <listitem>
+ <para>akonadiclient export [OPTIONS] COLLECTION FILE</para>
+ <para>Import an XML file inside the collection specified by PARENT. If the collection already exists, it's contents are merged with the contents of the collection in the XML file.</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>import</option></term>
+ <listitem>
+ <para>akonadiclient import [OPTIONS] PARENT FILE</para>
+ <para>Imports an XML file inside the collection specified by PARENT. If the collection already exists, it's contents are merged with the contents of the collection in the XML file.</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>info</option></term>
+ <listitem>
+ <para>akonadiclient info [OPTIONS] COLLECTION | ITEM</para>
+ <para>Show full information about a collection or item</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-c, --collection</option></term>
+ <listitem><para>Assume that a collection is specified</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-i, --item</option></term>
+ <listitem><para>Assume that an item is specified</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>show</option></term>
+ <listitem>
+ <para>akonadiclient show ITEM</para>
+ <para>Shows the raw payload of an item</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>tags</option></term>
+ <listitem>
+ <para>akonadiclient tags [OPTIONS]</para>
+ <para>List all known tags</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-b, --brief</option></term>
+ <listitem><para>Brief output - tag names only</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-u, --urls</option></term>
+ <listitem><para>Brief output - tag URLs only</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>update</option></term>
+ <listitem>
+ <para>akonadiclient update [OPTIONS] ITEM FILE</para>
+ <para>Updates the raw payload of ITEM with the contents of FILE</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Miscellaneous Commands</title>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>agents</option></term>
+ <listitem>
+ <para>akonadiclient agents [OPTIONS] [AGENTS...]</para>
+ <para>Allows managing of Akonadi agents like changing their state, restarting an agent or listing all agents and their state.</para>
+ <para>Options:</para>
+ <variablelist>
+
+ <varlistentry>
+ <term><option>-l, --list</option></term>
+ <listitem><para>List all agents</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-s, --setstate <replaceable>state</replaceable></option></term>
+ <listitem><para>Set the state for specified agents. Valid states are 'offline' and 'online'.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-g, --getstate</option></term>
+ <listitem><para>Get the state for specified agents</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-i, --info</option></term>
+ <listitem><para>Show information about the specified agents</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-r, --restart</option></term>
+ <listitem><para>Restarts the specified agents</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>-n, --dryrun</option></term>
+ <listitem><para>Run without making any actual changes</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>help</option></term>
+ <listitem>
+ <para>akonadiclient help [COMMAND]</para>
+ <para>Displays help for COMMAND. If COMMAND is not specified then it lists all the available commands</para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
+</refsect1>
+
+<refsect1>
+<title>Examples</title>
+<para><emphasis role="bold">akonadiclient list /</emphasis> - Lists all the collections under the root collection</para>
+<para><emphasis role="bold">akonadiclient export /Notes notes.xml</emphasis> - Exports all the items and sub-collections of the /Notes collection to the file 'notes.xml'</para>
+<para><emphasis role="bold">akonadiclient agents -l</emphasis> - Lists all agents</para>
+<para><emphasis role="bold">akonadiclient add /Notes note.txt</emphasis> - Adds the contents of the file note.txt as an item in the collection /Notes</para>
+</refsect1>
+
+</refentry>
More information about the kde-doc-english
mailing list