Merge lp:~stefanor/ibid/sphinxdoc-man into lp:ibid

[Stefano Rivera]

Move manpages into Sphinx docs

Sphinx 1.0 can build manpages. Rather nicely too.

[Jonathan Hitchcock (vhata)]

review: Approve

[Keegan Carruthers-Smith (keegan-csmith)]

review: Approve

=== modified file 'docs/Makefile'
--- docs/Makefile	2009-08-14 08:43:15 +0000
+++ docs/Makefile	2012-01-10 20:45:34 +0000
@@ -5,84 +5,126 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
+BUILDDIR      = _build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make man pages"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf _build/*
+	-rm -rf $(BUILDDIR)/*
 
 html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/html
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
-	@echo "Build finished. The HTML pages are in _build/html."
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in _build/dirhtml."
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
 pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
 json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
 htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in _build/htmlhelp."
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
 qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in _build/qthelp, like this:"
-	@echo "# qcollectiongenerator _build/qthelp/Ibid.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile _build/qthelp/Ibid.qhc"
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Ibid.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Ibid.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/Ibid"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Ibid"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
 latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in _build/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
 changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
-	@echo "The overview file is in _build/changes."
+	@echo "The overview file is in $(BUILDDIR)/changes."
 
 linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
-	      "or in _build/linkcheck/output.txt."
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
 doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in _build/doctest/output.txt."
+	      "results in $(BUILDDIR)/doctest/output.txt."

=== modified file 'docs/conf.py'
--- docs/conf.py	2011-02-26 16:48:17 +0000
+++ docs/conf.py	2012-01-10 20:45:34 +0000
@@ -45,7 +45,8 @@
 
 # General information about the project.
 project = u'Ibid'
-copyright = u'2008-2011, The Ibid Developers'
+AUTHORS = u'The Ibid Developers'
+copyright = u'2008-2012, %s' % AUTHORS
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -180,7 +181,7 @@
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
   ('index', 'Ibid.tex', u'Ibid Documentation',
-   u'The Ibid Developers', 'manual'),
+   AUTHORS, 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -200,6 +201,32 @@
 # If false, no module index is generated.
 #latex_use_modindex = True
 
+# -- Options for manpages ------------------------------------------------------
+
+man_pages = [
+    ('manpages/ibid.1', 'ibid', u'Run an Ibid bot', AUTHORS, 1),
+    ('manpages/ibid-db.1', 'ibid-db', u'Database management utility for Ibid',
+     AUTHORS, 1),
+    ('manpages/ibid-factpack.1', 'ibid-factpack',
+     u'Factoid-package management utility for Ibid', AUTHORS, 1),
+    ('manpages/ibid.ini.5', 'ibid.ini', u'Configuration file for Ibid',
+     AUTHORS, 5),
+    ('manpages/ibid-knab-import.1', 'ibid-knab-import',
+     u'Knab->Ibid Import utility', AUTHORS, 1),
+    ('manpages/ibid-memgraph.1', 'ibid-memgraph',
+     u'Memory usage graph generation utility for Ibid', AUTHORS, 1),
+    ('manpages/ibid-objgraph.1', 'ibid-objgraph',
+     u'Memory usage graph generation utility for Ibid', AUTHORS, 1),
+    ('manpages/ibid-pb-client.1', 'ibid-pb-client', 'RPC Client for Ibid',
+     AUTHORS, 1),
+    ('manpages/ibid-plugin.1', 'ibid-plugin',
+     u'Plugin testing developer environment for Ibid', AUTHORS, 1),
+    ('manpages/ibid-setup.1', 'ibid-setup',
+     u'Create a basic configuration file and database for an Ibid bot',
+     AUTHORS, 1),
+]
+
+
 # -- Options for extensions ----------------------------------------------------
 
 # pre-1.0 mode intersphinx:

=== modified file 'docs/index.rst'
--- docs/index.rst	2011-02-23 22:47:27 +0000
+++ docs/index.rst	2012-01-10 20:45:34 +0000
@@ -10,6 +10,7 @@
    plugins
    tutorial
    contributing
+   manpages/index
    api/index
    changes
 

=== renamed directory 'man' => 'docs/manpages'
=== renamed file 'man/ibid-db.1.md' => 'docs/manpages/ibid-db.1.rst'
--- man/ibid-db.1.md	2010-03-20 10:37:24 +0000
+++ docs/manpages/ibid-db.1.rst	2012-01-10 20:45:34 +0000
@@ -1,64 +1,68 @@
-% IBID-DB(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-db - Database management utility for Ibid
-
-# SYNOPSIS
-
-**ibid-db** *command* [*options*...]
-
-# DESCRIPTION
-
-This utility is for offline management of your Ibid bot's database.  Used for
-import, export, and upgrades.
-
-The export format is DBMS-agnostic and can be used to migrate between different
-databases.
-
-# COMMANDS
-
-**-e** *FILE*, **-\-export**=*FILE*
-:	Export DB contents to *FILE*.
-	Export format is JSON.
-	*FILE* can be **-** for *stdout* or can end in **.gz** for automatic gzip
-	compression.
-
-**-i** *FILE*, **-\-import**=*FILE*
-:	Import DB contents from *FILE* as exported by this utility.
-	*FILE* can be **-** for *stdin* or can end in **.gz** for automatic gzip
-	compression.
-
-:	**Note:** The DB must be empty first.
-
-**-u**, **-\-upgrade**
-:	Upgrade DB schema to the latest version.
-	You need to run this after upgrading your bot.
-
-:	**Note:** You should backup first.
-
-# OPTIONS
-
-**-\-version**
-:	Show the program's version and exit.
-
-**-h**, **-\-help**
-:	Show a help message and exit.
-
-**-v**, **-\-verbose**
-:	Turn on debugging output to stderr.
-
-# FILES
-
-*ibid.ini*
-:	Locates the database to act upon by looking for the
-	[**databases**].**ibid** value in the bot configuration file in the current
-	directory.
-
-# SEE ALSO
-`ibid` (1),
-`ibid.ini` (5),
-`ibid-setup` (1),
+=========
+ ibid-db
+=========
+
+SYNOPSIS
+========
+
+``ibid-db`` *command* [*options*...]
+
+DESCRIPTION
+===========
+
+This utility is for offline management of your Ibid bot's database.
+Used for import, export, and upgrades.
+
+The export format is DBMS-agnostic and can be used to migrate between
+different databases.
+
+COMMANDS
+========
+
+-e FILE, --export=FILE
+   Export DB contents to *FILE*.
+   Export format is JSON.
+   *FILE* can be ``-`` for *stdout* or can end in ``.gz`` for automatic
+   gzip compression.
+
+-i FILE, --import=FILE
+   Import DB contents from *FILE* as exported by this utility.
+   *FILE* can be ``-`` for *stdin* or can end in ``.gz`` for automatic
+   gzip compression.
+
+   **Note:** The DB must be empty first.
+
+-u, --upgrade
+   Upgrade DB schema to the latest version.
+   You need to run this after upgrading your bot.
+
+   **Note:** You should backup first.
+
+OPTIONS
+=======
+
+--version
+   Show the program's version and exit.
+
+-h, --help
+   Show a help message and exit.
+
+-v, --verbose
+   Turn on debugging output to stderr.
+
+FILES
+=====
+
+ibid.ini
+   Locates the database to act upon by looking for the
+   [**databases**].\ **ibid** value in the bot configuration file in the
+   current directory.
+
+SEE ALSO
+========
+``ibid``\ (1),
+``ibid.ini``\ (5),
+``ibid-setup``\ (1),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid-factpack.1.md' => 'docs/manpages/ibid-factpack.1.rst'
--- man/ibid-factpack.1.md	2010-03-20 10:37:24 +0000
+++ docs/manpages/ibid-factpack.1.rst	2012-01-10 20:45:34 +0000
@@ -1,70 +1,78 @@
-% IBID-FACTPACK(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-factpack - Factoid-package management utility for Ibid
-
-# SYNOPSIS
-
-**ibid-factpack** [**-s**] *factpack-file*  
-**ibid-factpack** **-r** [**-f**] *factpack-name*  
-**ibid-factpack** **-h**
-
-# DESCRIPTION
-
-This utility is for adding and removing sets of packaged factoids, known as
-factpacks, from your Ibid's factoid database.
+===============
+ ibid-factpack
+===============
+
+SYNOPSIS
+========
+
+| ``ibid-factpack`` [``-s``] *factpack-file*
+| ``ibid-factpack`` ``-r`` [``-f``] *factpack-name*
+| ``ibid-factpack`` ``-h``
+
+DESCRIPTION
+===========
+
+This utility is for adding and removing sets of packaged factoids, known
+as factpacks, from your Ibid's factoid database.
 
 The default mode is factpack loading.
 The *factpack-file* specified is loaded into the bot's database.
-Should the pack contain any facts with the same name as an existing fact in the
-bot's database, loading will be aborted, unless the *-s* option is supplied.
-
-Factpacks can be gzipped if the filename ends with **.gz**.
-
-When invoked with the **-r** option, the named factpack (original import
+Should the pack contain any facts with the same name as an existing fact
+in the bot's database, loading will be aborted, unless the ``-s`` option
+is supplied.
+
+Factpacks can be gzipped if the filename ends with ``.gz``.
+
+When invoked with the ``-r`` option, the named factpack (original import
 filename minus the extension) will be removed from the bot.
-If any of the facts contained in that pack were modified while loaded in the
-bot, unloading will be aborted, unless the **-f** option is supplied.
-
-# OPTIONS
-
-**-r**, **-\-remove**
-:	Remove the named factpack, rather than importing.
-
-**-f**, **-\-force**
-:	Force removal, if facts in the factpack were modified by users.
-
-**-s**, **-\-skip**
-:	Skip facts that clash with existing factoids, during import.
-
-**-h**, **-\-help**
-:	Show a help message and exit.
-
-# FACTPACKS
+If any of the facts contained in that pack were modified while loaded in
+the bot, unloading will be aborted, unless the ``-f`` option is
+supplied.
+
+OPTIONS
+=======
+
+-r, --remove
+   Remove the named factpack, rather than importing.
+
+-f, --force
+   Force removal, if facts in the factpack were modified by users.
+
+-s, --skip
+   Skip facts that clash with existing factoids, during import.
+
+-h, --help
+   Show a help message and exit.
+
+FACTPACKS
+=========
 
 Factpacks are JSON-encoded text files containing a list of facts.
 Each fact is a tuple of two lists: fact-names, fact-values.
 The same substitutions are available as in normal online Factoids.
 
-## Example:
-
-	[
-	 [["Hello", "Hi"], ["<reply> Hi There", "<action> waves"]],
-	 [["Bye"], ["<reply> kbye $who", "<reply> Cheers"]]
-	]
-
-# FILES
-
-*ibid.ini*
-:	Locates the database to act upon by looking for the
-	[**databases**].**ibid** value in the bot configuration file in the current
-	directory.
-
-# SEE ALSO
-
-`ibid` (1),
-`ibid.ini` (5),
+Example:
+--------
+::
+
+   [
+    [["Hello", "Hi"], ["<reply> Hi There", "<action> waves"]],
+    [["Bye"], ["<reply> kbye $who", "<reply> Cheers"]]
+   ]
+
+FILES
+=====
+
+ibid.ini
+   Locates the database to act upon by looking for the
+   [**databases**].\ **ibid** value in the bot configuration file in the
+   current directory.
+
+SEE ALSO
+========
+
+``ibid``\ (1),
+``ibid.ini``\ (5),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid-knab-import.1.md' => 'docs/manpages/ibid-knab-import.1.rst'
--- man/ibid-knab-import.1.md	2010-03-20 10:37:01 +0000
+++ docs/manpages/ibid-knab-import.1.rst	2012-01-10 20:45:34 +0000
@@ -1,50 +1,54 @@
-% IBID-KNAB-IMPORT(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-knab-import - Knab->Ibid Import utility
-
-# SYNOPSIS
-
-**ibid-knab-import** *knab-sa-url* *source* [*config-file*]
-
-# DESCRIPTION
-
-This utility imports users, last seen information, factoids, and URLs from a
-Knab bot's database into an Ibid.
+==================
+ ibid-knab-import
+==================
+
+SYNOPSIS
+========
+
+``ibid-knab-import`` *knab-sa-url* *source* [*config-file*]
+
+DESCRIPTION
+===========
+
+This utility imports users, last seen information, factoids, and URLs
+from a Knab bot's database into an Ibid.
 
 For best results, import directly into a brand new, clean Ibid install.
 
-On import, strings are converted to Unicode, guessing UTF-8 and falling back to
-detection.
-
-# OPTIONS
-
-*knab-sa-url*
-:	The SQLAlchemy URI for the Knab's database.
-	The format is **mysql://**_user_**:**_pass_**@**_hostname_**/**_dbname_
-
-*source*
-:	The name in the Ibid bot for the source that the Knab was previously
-	connected to.
-
-*config-file*
-:	If supplied, this is configuration file is used for locating the Ibid's
-	database rather than **ibid.ini**.
-
-# FILES
-
-*ibid.ini*
-:	Locates the database to act upon by looking for the
-	[**databases**].**ibid** value in the bot configuration file in the current
-	directory.
-
-# SEE ALSO
-
-`ibid` (1),
-`ibid.ini` (5),
-`ibid-setup` (1),
+On import, strings are converted to Unicode, guessing UTF-8 and falling
+back to detection.
+
+OPTIONS
+=======
+
+knab-sa-url
+   The SQLAlchemy URI for the Knab's database.
+   The format is
+   ``mysql://``\ *user*\ ``:``\ *pass*\ ``@``\ *hostname*\ ``/``\ *dbname*
+
+source
+   The name in the Ibid bot for the source that the Knab was previously
+   connected to.
+
+config-file
+   If supplied, this is configuration file is used for locating the
+   Ibid's database rather than ``ibid.ini``.
+
+FILES
+=====
+
+ibid.ini
+   Locates the database to act upon by looking for the
+   [**databases**].\ **ibid** value in the bot configuration file in the
+   current directory.
+
+SEE ALSO
+========
+
+``ibid``\ (1),
+``ibid.ini``\ (5),
+``ibid-setup``\ (1),
 http://ibid.omnia.za.net/,
 http://knab.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid-memgraph.1.md' => 'docs/manpages/ibid-memgraph.1.rst'
--- man/ibid-memgraph.1.md	2010-03-20 10:37:24 +0000
+++ docs/manpages/ibid-memgraph.1.rst	2012-01-10 20:45:34 +0000
@@ -1,44 +1,48 @@
-% IBID-MEMGRAPH(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-memgraph - Memory usage graph generation utility for Ibid
-
-# SYNOPSIS
-
-**ibid-memgraph** [*options*...] *logfile*  
-**ibid-memgraph** **-h**
-
-# DESCRIPTION
+===============
+ ibid-memgraph
+===============
+
+SYNOPSIS
+========
+
+| ``ibid-memgraph`` [*options*...] *logfile*
+| ``ibid-memgraph`` ``-h``
+
+DESCRIPTION
+===========
 
 This utility is for graphing memory usage from an Ibid bot configured to
 log such usage.
 
 Matplotlib is required for graphing.
 
-# OPTIONS
-
-**-o** *FILE*, **-\-output**=*FILE*
-:	Output to *FILE* instead of displaying interactive graph GUI.
-	*FILE* can be any format supported by Matplotlib, detected by the file
-	extension.
-
-**-d** *DPI*, **-\-dpi**=*DPI*
-	When outputting in raster formats, use *DPI* output DPI.
-
-**-h**, **-\-help**
-	Show a help message and exit.
-
-# FILES
-
-*logfile*
-:	A log file generated by loading the **memory** plugin into Ibid, which will
-	periodically log memory usage.
-	It can be gzip compressed, if the filename ends in **.gz**.
-
-# SEE ALSO
-`ibid` (1),
-`ibid-objgraph` (1),
+OPTIONS
+=======
+
+-o FILE, --output=FILE
+   Output to *FILE* instead of displaying interactive graph GUI.
+   *FILE* can be any format supported by Matplotlib, detected by the
+   file extension.
+
+-d DPI, --dpi=DPI
+   When outputting in raster formats, use *DPI* output DPI.
+
+-h, --help
+   Show a help message and exit.
+
+FILES
+=====
+
+logfile
+   A log file generated by loading the **memory** plugin into Ibid,
+   which will periodically log memory usage.
+   It can be gzip compressed, if the filename ends in ``.gz``.
+
+SEE ALSO
+========
+
+``ibid``\ (1),
+``ibid-objgraph``\ (1),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid-objgraph.1.md' => 'docs/manpages/ibid-objgraph.1.rst'
--- man/ibid-objgraph.1.md	2010-03-20 10:37:24 +0000
+++ docs/manpages/ibid-objgraph.1.rst	2012-01-10 20:45:34 +0000
@@ -1,51 +1,55 @@
-% IBID-OBJGRAPH(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-objgraph - Memory usage graph generation utility for Ibid
-
-# SYNOPSIS
-
-**ibid-objgraph** [*options*...] *logfile* *type*...  
-**ibid-objgraph** [*options*...] **-e** *TIME* *logfile*  
-**ibid-objgraph** **-h**
-
-# DESCRIPTION
+===============
+ ibid-objgraph
+===============
+
+SYNOPSIS
+========
+
+| ``ibid-objgraph`` [*options*...] *logfile* *type*...
+| ``ibid-objgraph`` [*options*...] ``-e`` *TIME* *logfile*
+| ``ibid-objgraph`` ``-h``
+
+DESCRIPTION
+===========
 
 This utility is for graphing object-type usage from an Ibid bot
 configured to log such usage.
 
 Matplotlib is required for graphing.
 
-# OPTIONS
-
-**-e** *TIME*, **-\-examine**=*TIME*
-:	Examine the object usage at time *TIME*, and print a sorted list of type
-	statistics at that time.
-	This function can be useful in determining which types to graph, when
-	chasing down a detected leak.
-
-**-o** *FILE*, **-\-output**=*FILE*
-:	Output to *FILE* instead of displaying interactive graph GUI.
-	*FILE* can be any format supported by Matplotlib, detected by the file
-	extension.
-
-**-d** *DPI*, **-\-dpi**=*DPI*
-:	When outputting in raster formats, use *DPI* output DPI.
-
-**-h**, **-\-help**
-	Show a help message and exit.
-
-# FILES
+OPTIONS
+=======
+
+-e TIME, --examine=TIME
+   Examine the object usage at time *TIME*, and print a sorted list of
+   type statistics at that time.
+   This function can be useful in determining which types to graph, when
+   chasing down a detected leak.
+
+-o FILE, --output=FILE
+   Output to *FILE* instead of displaying interactive graph GUI.
+   *FILE* can be any format supported by Matplotlib, detected by the
+   file extension.
+
+-d DPI, --dpi=DPI
+   When outputting in raster formats, use *DPI* output DPI.
+
+-h, --help
+   Show a help message and exit.
+
+FILES
+=====
 
 *logfile*
-:	A log file generated by loading the **memory** plugin into Ibid, which will
-	periodically log object usage.
-	It can be gzip compressed, if the filename ends in **.gz**.
-
-# SEE ALSO
-`ibid` (1),
-`ibid-memgraph` (1),
+   A log file generated by loading the **memory** plugin into Ibid,
+   which will periodically log object usage.
+   It can be gzip compressed, if the filename ends in ``.gz``.
+
+SEE ALSO
+========
+
+``ibid``\ (1),
+``ibid-memgraph``\ (1),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid-pb-client.1.md' => 'docs/manpages/ibid-pb-client.1.rst'
--- man/ibid-pb-client.1.md	2010-03-20 10:37:24 +0000
+++ docs/manpages/ibid-pb-client.1.rst	2012-01-10 20:45:34 +0000
@@ -1,18 +1,16 @@
-% IBID-PB-CLIENT(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-pb-client - RPC Client for Ibid
-
-# SYNOPSIS
-
-**ibid-pb-client** [*options*...] **message** *message*  
-**ibid-pb-client** [*options*...] **plugin** *feature* *method* [*parameter*...]  
-**ibid-pb-client** **-h**
-
-# DESCRIPTION
+================
+ ibid-pb-client
+================
+
+SYNOPSIS
+========
+
+| ``ibid-pb-client`` [*options*...] ``message`` *message*
+| ``ibid-pb-client`` [*options*...] ``plugin`` *feature* *method* [*parameter*...]
+| ``ibid-pb-client`` ``-h``
+
+DESCRIPTION
+===========
 
 This utility is for passing events to a running Ibid bot, or executing
 RPC-exposed functions remotely.
@@ -22,29 +20,33 @@
 *message* is a text message as could be sent to the bot by an IM source.
 The message is processed normally by the bot.
 
-*feature* is the name of the feature to invoke exposed method **method** on,
-directly.
-*parameter*s are passed directly to the method.
-They can be specified positionally or by key, using the same syntax as Python:
-_key_**=**_value_.
+*feature* is the name of the feature to invoke exposed method *method*
+on, directly.
+*parameter*\ s are passed directly to the method.
+They can be specified positionally or by key, using the same syntax as
+Python: *key*\ ``=``\ *value*.
 They may be encoded in JSON, if not valid JSON they will be treated as
 strings.
 
 The output is a JSON-encoded response.
 
-# OPTIONS
-
-**-s** *SERVER*, **-\-server**=*SERVER*
-:	Connect to the Ibid running on *SERVER*, by default it connects to
-	*localhost*.
-
-**-p** *PORT*, **-\-port**=*PORT*
-:	Connect to the **pb** source running on port *PORT*, by default 8789.
-
-**-h**, **-\-help**
-:	Show a help message and exit.
-
-# SEE ALSO
-
-`ibid` (1),
+OPTIONS
+=======
+
+-s SERVER, --server=SERVER
+   Connect to the Ibid running on *SERVER*, by default it connects to
+   *localhost*.
+
+-p PORT, --port=PORT
+   Connect to the **pb** source running on port *PORT*, by default 8789.
+
+-h, --help
+   Show a help message and exit.
+
+SEE ALSO
+========
+
+``ibid``\ (1),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid-plugin.1.md' => 'docs/manpages/ibid-plugin.1.rst'
--- man/ibid-plugin.1.md	2010-03-20 10:37:24 +0000
+++ docs/manpages/ibid-plugin.1.rst	2012-01-10 20:45:34 +0000
@@ -1,71 +1,77 @@
-% IBID-PLUGIN(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-plugin \- Plugin testing developer environment for Ibid
-
-# SYNOPSIS
-
-**ibid-plugin** [*options*...] [*plugin*[**-**]|_plugin_**.**_Processor_[**-**]...]
-
-# DESCRIPTION
-
-This utility is for testing Ibid plugins without the full bot environment.
-This means testing can be performed offline and without loading all the
-available plugins.
+=============
+ ibid-plugin
+=============
+
+SYNOPSIS
+========
+
+``ibid-plugin`` [*options*...] [*plugin*\ [``-``]|\ *plugin*\ ``.``\ *Processor*\ [``-``]...]
+
+DESCRIPTION
+===========
+
+This utility is for testing Ibid plugins without the full bot
+environment.  This means testing can be performed offline and without
+loading all the available plugins.
 
 This should be run in a configured Ibid bot directory.
 
 All the listed plugins and Processors will be loaded on start-up.
 Naming a plugin loads the complete plugin.
-Suffixing a **-** to the name, ignores that plugin or Processor instead of
-loading it.
-
-# OPTIONS
-
-**-c**, **-\-configured**
-:	Load all configured plugins, instead of only the core and requested
-	plugins.
-
-**-o**, **-\-only**
-:	Don't load the Ibid core plugins, only the plugins requested.
-	Note that without the **core** plugin to pre- and post-process events, most
-	other plugins won't function correctly.
-
-**-p**, **-\-public**
-:	By default, **ibid-plugin** emulates a private conversation with the bot.
-	With this option, the conversation is considered to be public and the
-	bot will have to be addressed to provoke a response.
-
-**-v**, **-\-verbose**
-:	Increase verbosity.
-	The final form of each *Event* object will be displayed before any
-	responses.
-
-**-h**, **-\-help**
-Show a help message and exit.
-
-# FILES
-
-*ibid.ini*
-:	Locates the database to act upon by looking for the
-	[**databases**].**ibid** value in the bot configuration file in the current
-	directory.
-
-# BUGS
-
-**ibid-plugin** doesn't emulate a complete Ibid environment, and will ignore
-all of the following:
-
-* Delayed and periodically executed functions.
-* Messages to alternate sources.
-* Messages directly dispatched, rather than added to responses.
-* Permissions. All permissions are granted to the user.
-
-# SEE ALSO
-`ibid` (1),
-`ibid.ini` (5),
-`ibid-setup` (1),
+Suffixing a ``-`` to the name, ignores that plugin or Processor instead
+of loading it.
+
+OPTIONS
+=======
+
+-c, --configured
+   Load all configured plugins, instead of only the core and requested
+   plugins.
+
+-o, --only
+   Don't load the Ibid core plugins, only the plugins requested.
+   Note that without the **core** plugin to pre- and post-process
+   events, most other plugins won't function correctly.
+
+-p, --public
+   By default, **ibid-plugin** emulates a private conversation with the
+   bot.
+   With this option, the conversation is considered to be public and the
+   bot will have to be addressed to provoke a response.
+
+-v, --verbose
+   Increase verbosity.
+   The final form of each *Event* object will be displayed before any
+   responses.
+
+-h, --help
+   Show a help message and exit.
+
+FILES
+=====
+
+ibid.ini
+   Locates the database to act upon by looking for the
+   [**databases**].\ **ibid** value in the bot configuration file in the
+   current directory.
+
+BUGS
+====
+
+**ibid-plugin** doesn't emulate a complete Ibid environment, and will
+ignore all of the following:
+
+ * Delayed and periodically executed functions.
+ * Messages to alternate sources.
+ * Messages directly dispatched, rather than added to responses.
+ * Permissions. All permissions are granted to the user.
+
+SEE ALSO
+========
+
+``ibid``\ (1),
+``ibid.ini``\ (5),
+``ibid-setup``\ (1),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid-setup.1.md' => 'docs/manpages/ibid-setup.1.rst'
--- man/ibid-setup.1.md	2010-03-15 20:23:11 +0000
+++ docs/manpages/ibid-setup.1.rst	2012-01-10 20:45:34 +0000
@@ -1,36 +1,40 @@
-% IBID-SETUP(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid-setup - Create a basic configuration file and database for an Ibid bot
-
-# SYNOPSIS
+============
+ ibid-setup
+============
+
+SYNOPSIS
+========
 
 **ibid-setup**
 
-# DESCRIPTION
+DESCRIPTION
+===========
 
 This program sets up everything that a new Ibid bot needs before it can run.
 It asks a series of questions about the new bot, and writes out a basic
-configuration file - `ibid.ini` (5) - to the current directory.
-It also creates a database for the bot, by default a SQLite database in the
-current directory.
-
-This should be run in the directory which will become the new Ibid bot's base.
-
-Should there be an existing **ibid.ini** in the current directory, it will be
-used, and the only questions asked will be for adding an administrative user.
-These can safely be skipped with a **^C**.
-
-# FILES
-
-*ibid.ini*
-:	The Ibid bot's configuration file, will be created if it doesn't exist.
-
-# SEE ALSO
-
-`ibid` (1),
-`ibid.ini` (5),
+configuration file - ``ibid.ini``\ (5) - to the current directory.
+It also creates a database for the bot, by default a SQLite database in
+the current directory.
+
+This should be run in the directory which will become the new Ibid bot's
+base.
+
+Should there be an existing ``ibid.ini`` in the current directory, it
+will be used, and the only questions asked will be for adding an
+administrative user.
+These can safely be skipped with a ``^C``.
+
+FILES
+=====
+
+ibid.ini
+   The Ibid bot's configuration file, will be created if it doesn't exist.
+
+SEE ALSO
+========
+
+``ibid``\ (1),
+``ibid.ini``\ (5),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid.1.md' => 'docs/manpages/ibid.1.rst'
--- man/ibid.1.md	2010-03-15 20:23:11 +0000
+++ docs/manpages/ibid.1.rst	2012-01-10 20:45:34 +0000
@@ -1,41 +1,44 @@
-% IBID(1) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid - Run an Ibid bot
-
-# SYNOPSIS
-
-**ibid** [*config-file*]
-
-# DESCRIPTION
+======
+ ibid
+======
+
+SYNOPSIS
+========
+
+``ibid`` [*config-file*]
+
+DESCRIPTION
+===========
 
 This runs an Ibid bot in the foreground.
 
-There should there be an existing **ibid.ini** (created by
-`ibid-setup` (1))
+There should there be an existing ``ibid.ini`` (created by
+``ibid-setup``\ (1))
 in the current directory or one should be provided on the command line.
 
-Where possible, you should run **twistd -n ibid** instead of this
+Where possible, you should run ``twistd -n ibid`` instead of this
 program, as otherwise some classes of errors go unreported.
 See **BUGS**.
 
-# BUGS
+BUGS
+====
 
 Exceptions in twisted callbacks can go unnoticed in this program.
 That has no harmful effects, but the developers may miss out on some
 good bug reports.
 
-# FILES
+FILES
+=====
 
 *ibid.ini*
-:	The Ibid bot's configuration file, will be created if it doesn't exist.
-
-# SEE ALSO
-
-`ibid.ini` (5),
-`ibid-setup` (1),
-`twistd` (1),
+   The Ibid bot's configuration file, will be created if it doesn't exist.
+
+SEE ALSO
+========
+
+``ibid.ini``\ (5),
+``ibid-setup``\ (1),
+``twistd``\ (1),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== renamed file 'man/ibid.ini.5.md' => 'docs/manpages/ibid.ini.5.rst'
--- man/ibid.ini.5.md	2011-06-13 11:51:01 +0000
+++ docs/manpages/ibid.ini.5.rst	2012-01-10 20:45:34 +0000
@@ -1,119 +1,130 @@
-% IBID.INI(5) Ibid Multi-protocol Bot | Ibid 0.1
-% Stefano Rivera
-% March 2010
-
-# NAME
-
-ibid.ini - Configuration file for Ibid
-
-# DESCRIPTION
-
-ibid.ini contains all the configuration for an Ibid bot.
-
-A complete description of the contents of this file is out of the scope of this
-manpage.
-For more details see the Ibid documentation: http://ibid.omnia.za.net/docs/
-
-Lines beginning with **#** are considered to be comments and ignored.
-To use a **#** symbol in an option (e.g. an IRC channel name), quote the
-option with double-quotes, e.g. **channels**=**"#ibid",**
+==========
+ ibid.ini
+==========
+
+NAME
+====
+
+DESCRIPTION
+===========
+
+``ibid.ini`` contains all the configuration for an Ibid bot.
+
+A complete description of the contents of this file is out of the scope
+of this manpage.
+For more details see the Ibid HTML documentation:
+http://ibid.omnia.za.net/docs/
+
+Lines beginning with ``#`` are considered to be comments and ignored.
+To use a ``#`` symbol in an option (e.g. an IRC channel name), quote the
+option with double-quotes, e.g. ``channels = "#ibid",``
 
 This file will be written to by the bot when configuration settings are
 altered online.
 It can also be edited manually and a running bot told to
-**"reload config"**.
+``reload config``.
 Manual edits and comments will be preserved when the bot modifies its
 own configuration, provided that they have not been edited since bot
 start-up or the last config reload.
 
-# SECTIONS
+SECTIONS
+========
 
-## auth
+auth
+----
 
 Settings related to permissions and authentication.
-Permissions listed in **auth**.**permissions** are granted to all users unless
-revoked by source or account.
+Permissions listed in **auth**.\ **permissions** are granted to all
+users unless revoked by source or account.
 
-## sources
+sources
+-------
 
 Sources are Ibid connections to an IM service.
 They range from IRC networks to the bot's built-in HTTP server.
 
 Each source is configured in a section named after the source.
-The source name will define the driver that the source should use, unless a
-**type** option is provided.
+The source name will define the driver that the source should use,
+unless a ``type`` option is provided.
 
 Sources can be disabled by setting
-**disabled**=**True**.
+``disabled = True``.
 
-## plugins
+plugins
+-------
 
 Plugin configuration.
 Each plugin is configured within a section named after the plugin.
 
-**cachedir**
-:	The directory that temporary files (such as downloaded data), useful to be
-	the bot but expendable, is stored in.
-
-**autoload**
-:	If **True**, all plugins not explicitly ignored will be loaded.
-	(Note that some plugins mark themselves as non-auto-loadable).
-	Defaults to **True**.
-
-**load**
-:	The list of plugins (or **plugin**.**Processor**s) to load.
-
-**noload**
-:	The list of plugins (or **plugin**.**Processor**s) to ignore and not load.
-
-**core**.**names**
-:	The names that the bot should respond to.
-
-**core**.**ignore**
-:	Nicks that the bot should completely ignore (e.g. other bots).
-
-# EXAMPLE
-
-	botname = joebot
-	logging = logging.ini
-
-	[auth]
-	    methods = password,
-	    timeout = 300
-	    permissions = +factoid, +karma, +sendmemo, +recvmemo, +feeds, +publicresponse
-
-	[sources]
-	    [[telnet]]
-	    [[timer]]
-	    [[http]]
-	        url = http://joebot.example.com
-	    [[smtp]]
-	    [[pb]]
-	    [[atrum]]
-	        channels = "#ibid",
-	        nick = $botname
-	        type = irc
-	        auth = hostmask, nickserv
-	        server = irc.atrum.org
-
-	[plugins]
-	    cachedir = /tmp/ibid
-	    [[core]]
-	        names = $botname, bot, ant
-	        ignore = ,
-
-	[databases]
-	    ibid = sqlite:///ibid.db
-
-# FILES
-
-*logging*.*ini*
-:	A standard Python **logging**.**config** configuration file describing
-	loggers, handlers, and formatters for log messages.
-	See http://docs.python.org/library/logging.html
-
-# SEE ALSO
-`ibid` (1),
-`ibid.ini` (5),
-`twistd` (1),
+cachedir
+   The directory that temporary files (such as downloaded data), useful
+   to be the bot but expendable, is stored in.
+
+autoload
+   If ``True``, all plugins not explicitly ignored will be loaded.
+   (Note that some plugins mark themselves as non-auto-loadable).
+   Defaults to ``True``.
+
+load
+   The list of plugins (or **plugin**.\ **Processor**\ s) to load.
+
+noload
+   The list of plugins (or **plugin**.\ **Processor**\ s) to ignore and
+   not load.
+
+core.names
+   The names that the bot should respond to.
+
+core.ignore
+   Nicks that the bot should completely ignore (e.g. other bots).
+
+EXAMPLE
+=======
+::
+
+   botname = joebot
+   logging = logging.ini
+
+   [auth]
+       methods = password,
+       timeout = 300
+       permissions = +factoid, +karma, +sendmemo, +recvmemo, +feeds, +publicresponse
+
+   [sources]
+       [[telnet]]
+       [[timer]]
+       [[http]]
+           url = http://joebot.example.com
+       [[smtp]]
+       [[pb]]
+       [[atrum]]
+           channels = "#ibid",
+           nick = $botname
+           type = irc
+           auth = hostmask, nickserv
+           server = irc.atrum.org
+
+   [plugins]
+       cachedir = /tmp/ibid
+       [[core]]
+           names = $botname, bot, ant
+           ignore = ,
+
+   [databases]
+       ibid = sqlite:///ibid.db
+
+FILES
+=====
+
+logging.ini
+   A standard Python **logging**.\ **config** configuration file describing
+   loggers, handlers, and formatters for log messages.
+   See http://docs.python.org/library/logging.html
+
+SEE ALSO
+========
+
+``ibid``\ (1),
 http://ibid.omnia.za.net/
+
+.. vi: set et sta sw=3 ts=3:

=== added file 'docs/manpages/index.rst'
--- docs/manpages/index.rst	1970-01-01 00:00:00 +0000
+++ docs/manpages/index.rst	2012-01-10 20:45:34 +0000
@@ -0,0 +1,18 @@
+Command line utility Reference
+==============================
+
+.. toctree::
+   :maxdepth: 2
+
+   ibid-db.1
+   ibid-factpack.1
+   ibid-knab-import.1
+   ibid-memgraph.1
+   ibid-objgraph.1
+   ibid-pb-client.1
+   ibid-plugin.1
+   ibid-setup.1
+   ibid.1
+   ibid.ini.5
+
+.. vi: set et sta sw=3 ts=3:

=== removed file 'man/Makefile'
--- man/Makefile	2010-03-15 20:23:11 +0000
+++ man/Makefile	1970-01-01 00:00:00 +0000
@@ -1,13 +0,0 @@
-MANPAGES=$(patsubst %.md,%,$(wildcard *.md))
-
-all: $(MANPAGES)
-
-clean:
-	rm -f $(MANPAGES)
-
-%: %.md
-# Incorrect escaping in code blocks:
-# http://code.google.com/p/pandoc/issues/detail?id=223
-	pandoc -s -t man $< | sed -e '/^[^.]/ s/\\"/"/g' > $@
-
-.PHONY: all clean

=== removed file 'man/README'
--- man/README	2010-03-15 20:23:11 +0000
+++ man/README	1970-01-01 00:00:00 +0000
@@ -1,4 +0,0 @@
-All files in this directory are:
-
-Copyright (c) 2010, Stefano Rivera
-Released under terms of the MIT/X/Expat Licence. See COPYING for details.