doc/source: Big documentation reorganisation.

Due to the new C++ API and because I wanted to include some tutorials,
the documentation is now seperated into 4 sections:

	library   => Documentation of modules.
	tutorials => Tutorials for using python-apt and contributing
	whatsnew  => Release notes
	c++       => Documentation,Tutorials for the C++ API

This commit also includes a new overview page, like the Python
documentation.

26 files changed, 440 insertions, 177 deletions

diff --git a/doc/source/apt/index.rst b/doc/source/apt/index.rst
deleted file mode 100644
index 9cd6ef45..00000000
--- a/doc/source/apt/index.rst
+++ /dev/null
@@ -1,56 +0,0 @@
-:mod:`apt` --- Highlevel apt package
-=====================================
-The highlevel apt package provides a lot of functionality, all
-with an easy-to-use interface.
-
-.. warning::
-    The API of this package is not considered stable. Evenmore, it is considered
-    to change the naming conventions in future to lowercase_with_underscores.
-
-    In case this happens, the API will still be kept compatible, with the old
-    functions provided as deprecated ones.
-
-.. automodule:: apt
-
-
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-
-   *
-
-
-Classes exported in apt
-------------------------
-These classes are defined in the submodules, but are also exported directly
-in the package.
-
-.. class:: Cache
-
-    Please see :class:`apt.cache.Cache` for documentation.
-
-.. class:: Cdrom
-
-    Please see :class:`apt.cdrom.Cdrom` for documentation.
-
-.. class:: CdromProgress
-
-    Please see :class:`apt.progress.CdromProgress` for documentation.
-
-.. class:: FetchProgress
-
-    Please see :class:`apt.progress.FetchProgress` for documentation.
-
-.. class:: InstallProgress
-
-    Please see :class:`apt.progress.InstallProgress` for documentation.
-
-.. class:: OpProgress
-
-    Please see :class:`apt.progress.OpProgress` for documentation.
-
-.. class:: Package
-
-    Please see :class:`apt.package.Package` for documentation.
-
diff --git a/doc/source/apt/progress.rst b/doc/source/apt/progress.rst
deleted file mode 100644
index 8989aa27..00000000
--- a/doc/source/apt/progress.rst
+++ /dev/null
@@ -1,37 +0,0 @@
-:mod:`apt.progress` --- Classes for progress reporting
-======================================================
-.. automodule:: apt.progress
-
-.. warning::
-
-    This class is currently under re-organisation. Therefore, the API may
-    change soon. The old names will still be kept until it is safe to remove
-    them.
-
-
-
-Classes without output
-----------------------
-.. autoclass:: FetchProgress
-    :members:
-.. autoclass:: OpProgress
-    :members:
-.. autoclass:: CdromProgress
-    :members:
-.. autoclass:: DumbInstallProgress
-    :members:
-
-Implementing classes for text output
-------------------------------------
-.. autoclass:: TextFetchProgress
-    :members:
-.. autoclass:: OpTextProgress
-    :members:
-.. autoclass:: InstallProgress
-    :members:
-.. autoclass:: DpkgInstallProgress
-    :members:
-
-
-
-
diff --git a/doc/source/aptsources/index.rst b/doc/source/aptsources/index.rst
deleted file mode 100644
index 898fbf74..00000000
--- a/doc/source/aptsources/index.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-:mod:`aptsources` --- Working with sources.list
-=====================================================
-.. automodule:: aptsources
-
-.. toctree::
-    :maxdepth: 2
-    :glob:
-
-    *
-
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 86e6868c..0a9d5ed5 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -54,7 +54,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
 intersphinx_mapping = {'http://docs.python.org/': None}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['.templates']
+templates_path = ['templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
@@ -63,7 +63,7 @@ source_suffix = '.rst'
 #source_encoding = 'utf-8'
 
 # The master toctree document.
-master_doc = 'index'
+#master_doc = 'contents'
 
 # General information about the project.
 project = u'python-apt'
@@ -77,12 +77,21 @@ copyright = u'2009, Julian Andres Klode <jak@debian.org>'
 try:
     release=os.environ['DEBVER']
 except KeyError:
-    from debian_bundle.changelog import Changelog
-    changes = Changelog(open('../../debian/changelog'))
-    # The full version, including alpha/beta/rc tags.
-    release = changes.full_version
-
-version = '.'.join(release.split('.')[:3])
+    from subprocess import Popen, PIPE
+    p1 = Popen(["dpkg-parsechangelog", "-l../../debian/changelog"],
+               stdout=PIPE)
+    p2 = Popen(["sed", "-n", 's/^Version: //p'], stdin=p1.stdout, stdout=PIPE)
+    release = p2.communicate()[0]
+
+# Handle the alpha release scheme.
+if int(release.split("~")[0].split(".")[2]) >= 90:
+    version_s = release.split("~")[0].split(".")[:3]
+    version_s[1] = str(int(version_s[1]) + 1)
+    version_s[2] = "0"
+    version = '.'.join(version_s)
+    del version_s
+else:
+    version = '.'.join(release.split("~")[0].split('.')[:3])
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -150,7 +159,7 @@ html_static_path = ['.static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -161,7 +170,7 @@ html_static_path = ['.static']
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-#html_additional_pages = {}
+html_additional_pages = {"index": "indexcontent.html"}
 
 # If false, no module index is generated.
 #html_use_modindex = True
@@ -199,7 +208,7 @@ htmlhelp_basename = 'python-aptdoc'
 # Grouping the document tree into LaTeX files. List of tuples
 # (source index, target name, title, author, document class [howto/manual]).
 latex_documents = [
-  ('index', 'python-apt.tex', ur'python-apt Documentation',
+  ('contents', 'python-apt.tex', ur'python-apt Documentation',
    ur'Julian Andres Klode <jak@debian.org>', 'manual'),
 ]
 
diff --git a/doc/source/contents.rst b/doc/source/contents.rst
new file mode 100644
index 00000000..3c9fb511
--- /dev/null
+++ b/doc/source/contents.rst
@@ -0,0 +1,20 @@
+Python APT Documentation contents
+======================================
+
+Contents:
+
+.. toctree::
+
+   whatsnew/index
+   library/index
+   tutorials/index
+   c++/index
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/doc/source/examples/apt-cdrom.py b/doc/source/examples/apt-cdrom.py
new file mode 100644
index 00000000..a20b0f12
--- /dev/null
+++ b/doc/source/examples/apt-cdrom.py
@@ -0,0 +1,70 @@
+#!/usr/bin/python
+import sys
+
+import apt_pkg
+import apt
+
+
+def show_help():
+    print ("apt %s compiled on %s %s" % (apt_pkg.VERSION,
+                    apt_pkg.DATE, apt_pkg.TIME))
+    if apt_pkg.config.find_b("version"):
+        return 0
+
+    # Copied from apt-cdrom
+    print ("Usage: apt-cdrom [options] command\n"
+           "\n"
+           "apt-cdrom is a tool to add CDROM's to APT's source list. The\n"
+           "CDROM mount point and device information is taken from apt.conf\n"
+           "and /etc/fstab.\n"
+           "\n"
+           "Commands:\n"
+           "   add - Add a CDROM\n"
+           "   ident - Report the identity of a CDROM\n"
+           "\n"
+           "Options:\n"
+           "  -h   This help text\n"
+           "  -d   CD-ROM mount point\n"
+           "  -r   Rename a recognized CD-ROM\n"
+           "  -m   No mounting\n"
+           "  -f   Fast mode, don't check package files\n"
+           "  -a   Thorough scan mode\n"
+           "  -c=? Read this configuration file\n"
+           "  -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n"
+           "See fstab(5)")
+    return 0
+
+
+def main(args):
+    arguments = apt_pkg.parse_commandline(apt_pkg.config,
+                    [('h', "help", "help"),
+                     ('v', "version", "version"),
+                     ('d', "cdrom", "Acquire::cdrom::mount", "HasArg"),
+                     ('r', "rename", "APT::CDROM::Rename"),
+                     ('m', "no-mount", "APT::CDROM::NoMount"),
+                     ('f', "fast", "APT::CDROM::Fast"),
+                     ('n', "just-print", "APT::CDROM::NoAct"),
+                     ('n', "recon", "APT::CDROM::NoAct"),
+                     ('n', "no-act", "APT::CDROM::NoAct"),
+                     ('a', "thorough", "APT::CDROM::Thorough"),
+                     ('c', "config-file", "", "ConfigFile"),
+                     ('o', "option", "", "ArbItem")], args)
+
+    if apt_pkg.config.find_b("help") or apt_pkg.config.find_b("version"):
+        return show_help()
+
+    progress = apt.progress.text.CdromProgress()
+    cdrom = apt_pkg.Cdrom()
+
+    if not arguments:
+        return show_help()
+    elif arguments[0] == 'add':
+        cdrom.add(progress)
+    elif arguments[0] == 'ident':
+        cdrom.ident(progress)
+    else:
+        sys.stderr.write('E: Invalid operation %s\n' % arguments[0])
+        return 1
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))
diff --git a/doc/source/index.rst b/doc/source/index.rst
deleted file mode 100644
index 2e05061a..00000000
--- a/doc/source/index.rst
+++ /dev/null
@@ -1,41 +0,0 @@
-Welcome to python-apt's documentation!
-======================================
-
-This is the official documentation for version |version| of the Python bindings
-for Debian's famous APT package management.
-
-This documentation has been created by Sphinx, using reStructuredText files
-written by Julian Andres Klode <jak@debian.org>, and in case of the apt
-package, from the documentation shipped in the modules.
-
-
-Contents:
-
-.. toctree::
-   :hidden:
-
-   whatsnew/index
-
-.. toctree::
-   :maxdepth: 2
-
-   whatsnew/0.8.0
-   apt/index
-   apt_pkg
-   apt_inst
-   aptsources/index
-   contributing
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
-
-TODO
-======
-.. todolist::
diff --git a/doc/source/apt/cache.rst b/doc/source/library/apt.cache.rst
index ddb2dc64..ddb2dc64 100644
--- a/doc/source/apt/cache.rst
+++ b/doc/source/library/apt.cache.rst
diff --git a/doc/source/apt/cdrom.rst b/doc/source/library/apt.cdrom.rst
index 56381f14..56381f14 100644
--- a/doc/source/apt/cdrom.rst
+++ b/doc/source/library/apt.cdrom.rst
diff --git a/doc/source/apt/debfile.rst b/doc/source/library/apt.debfile.rst
index 7133b5a8..7133b5a8 100644
--- a/doc/source/apt/debfile.rst
+++ b/doc/source/library/apt.debfile.rst
diff --git a/doc/source/apt/package.rst b/doc/source/library/apt.package.rst
index 4b143b8a..4b143b8a 100644
--- a/doc/source/apt/package.rst
+++ b/doc/source/library/apt.package.rst
diff --git a/doc/source/apt/progress.gtk2.rst b/doc/source/library/apt.progress.gtk2.rst
index a83ab111..b16c903c 100644
--- a/doc/source/apt/progress.gtk2.rst
+++ b/doc/source/library/apt.progress.gtk2.rst
@@ -1,5 +1,5 @@
-:mod:`apt.progress.gtk2` --- GTK widgets
-========================================
+:mod:`apt.progress.gtk2` --- Progress reporting for GTK+ interfaces
+===================================================================
 .. automodule:: apt.progress.gtk2
 
 
diff --git a/doc/source/library/apt.progress.qt4.rst b/doc/source/library/apt.progress.qt4.rst
new file mode 100644
index 00000000..cd06a4e6
--- /dev/null
+++ b/doc/source/library/apt.progress.qt4.rst
@@ -0,0 +1,3 @@
+:mod:`apt.progress.qt4` --- Progress reporting for Qt4 interfaces
+=================================================================
+Not written yet.
diff --git a/doc/source/library/apt.progress.text.rst b/doc/source/library/apt.progress.text.rst
new file mode 100644
index 00000000..4e051e31
--- /dev/null
+++ b/doc/source/library/apt.progress.text.rst
@@ -0,0 +1,21 @@
+:mod:`apt.progress.text` --- Progress reporting for text interfaces
+===================================================================
+.. automodule:: apt.progress.text
+
+
+Acquire Progress Reporting
+--------------------------
+.. autoclass:: AcquireProgress
+    :members:
+
+
+CD-ROM Progress Reporting
+--------------------------
+.. autoclass:: CdromProgress
+    :members:
+
+Operation Progress Reporting
+-----------------------------
+.. autoclass:: OpProgress
+    :members:
+
diff --git a/doc/source/apt_inst.rst b/doc/source/library/apt_inst.rst
index cd371e36..eef3db9f 100644
--- a/doc/source/apt_inst.rst
+++ b/doc/source/library/apt_inst.rst
@@ -108,15 +108,15 @@ Example: Emulating :program:`dpkg` :option:`--extract`
 Here is a code snippet which emulates dpkg -x. It can be run as
 :program:`tool` :option:`pkg.deb` :option:`outdir`.
 
-.. literalinclude:: examples/dpkg-extract.py
+.. literalinclude:: ../examples/dpkg-extract.py
 
 
 .. _emulating-dpkg-contents:
 
 Example: Emulating :program:`dpkg` :option:`--contents`
 -------------------------------------------------------
-.. literalinclude:: examples/dpkg-contents.py
+.. literalinclude:: ../examples/dpkg-contents.py
 
 Example: Emulating :program:`dpkg` :option:`--info`
 ----------------------------------------------------
-.. literalinclude:: examples/dpkg-info.py
+.. literalinclude:: ../examples/dpkg-info.py
diff --git a/doc/source/apt_pkg.rst b/doc/source/library/apt_pkg.rst
index 9a14266e..6fccc207 100644
--- a/doc/source/apt_pkg.rst
+++ b/doc/source/library/apt_pkg.rst
@@ -451,7 +451,7 @@ Resolving Dependencies
 
 Example
 ^^^^^^^
-.. literalinclude:: examples/cache-pkgfile.py
+.. literalinclude:: ../examples/cache-pkgfile.py
 
 
 :class:`Package`
@@ -542,7 +542,7 @@ Example
 
 Example:
 ^^^^^^^^^
-.. literalinclude:: examples/cache-packages.py
+.. literalinclude:: ../examples/cache-packages.py
 
 
 
@@ -715,7 +715,7 @@ Example: Find all missing dependencies
 With the help of Dependency.AllTargets(), you can easily find all packages with
 broken dependencies:
 
-.. literalinclude:: examples/missing-deps.py
+.. literalinclude:: ../examples/missing-deps.py
 
 
 :class:`Description`
@@ -1139,7 +1139,7 @@ installation.
     the file using the parameter *destfile*. You can not combine both.
 
 
-Hashes 
+Hashes
 ------
 The apt_pkg module also provides several hash functions. If you develop
 applications with python-apt it is often easier to use these functions instead
@@ -1281,7 +1281,22 @@ section as a string.
 
         Return a list of keys in the section.
 
-.. autofunction:: rewrite_section(section, order, rewrite_list)
+.. function:: rewrite_section(section: TagSection, order: list, rewrite_list: list) -> str
+
+    Rewrite the section given by *section* using *rewrite_list*, and order the
+    fields according to *order*.
+
+    The parameter *order* is a :class:`list` object containing the names of the
+    fields in the order they should appear in the rewritten section.
+    :data:`apt_pkg.REWRITE_PACKAGE_ORDER` and
+    :data:`apt_pkg.REWRITE_SOURCE_ORDER` are two predefined lists for rewriting
+    package and source sections, respectively.
+
+    The parameter *rewrite_list* is a list of tuples of the form
+    ``(tag, newvalue[, renamed_to])``, whereas *tag* describes the field which
+    should be changed, *newvalue* the value which should be inserted or
+    ``None`` to delete the field, and the optional *renamed_to* can be used
+    to rename the field.
 
 .. data:: REWRITE_PACKAGE_ORDER
 
@@ -1329,7 +1344,7 @@ Dependencies
 .. function:: parse_src_depends(depends)
 
     Parse the string *depends* which contains dependency information as
-    specified in Debian Policy, Section 7.1. 
+    specified in Debian Policy, Section 7.1.
 
     Returns a list. The members of this list are lists themselves and contain
     one or more tuples in the format ``(package,version,operation)`` for every
diff --git a/doc/source/aptsources/distinfo.rst b/doc/source/library/aptsources.distinfo.rst
index 96f9445d..033ef483 100644
--- a/doc/source/aptsources/distinfo.rst
+++ b/doc/source/library/aptsources.distinfo.rst
@@ -1,10 +1,11 @@
 :mod:`aptsources.distinfo` --- provide meta information for distro repositories
 ===============================================================================
+.. note::
+
+    This part of the documentation is created automatically.
+
 
 .. automodule:: aptsources.distinfo
     :members:
     :undoc-members:
 
-    .. note::
-
-        This part of the documentation is created automatically.
diff --git a/doc/source/aptsources/distro.rst b/doc/source/library/aptsources.distro.rst
index 06ca0fda..6ebe438c 100644
--- a/doc/source/aptsources/distro.rst
+++ b/doc/source/library/aptsources.distro.rst
@@ -1,10 +1,11 @@
 :mod:`aptsources.distro` --- Distribution abstraction of the sources.list
 ===============================================================================
+.. note::
+
+    This part of the documentation is created automatically.
+
 
 .. automodule:: aptsources.distro
     :members:
     :undoc-members:
 
-    .. note::
-
-        This part of the documentation is created automatically.
diff --git a/doc/source/aptsources/sourceslist.rst b/doc/source/library/aptsources.sourceslist.rst
index 509db3ce..79b8dd01 100644
--- a/doc/source/aptsources/sourceslist.rst
+++ b/doc/source/library/aptsources.sourceslist.rst
@@ -1,10 +1,11 @@
 :mod:`aptsources.sourceslist` --- Provide an abstraction of the sources.list
 ============================================================================
+.. note::
+
+    This part of the documentation is created automatically.
+
 
 .. automodule:: aptsources.sourceslist
     :members:
     :undoc-members:
 
-    .. note::
-
-        This part of the documentation is created automatically.
diff --git a/doc/source/library/index.rst b/doc/source/library/index.rst
new file mode 100644
index 00000000..dfbd8eec
--- /dev/null
+++ b/doc/source/library/index.rst
@@ -0,0 +1,36 @@
+Python APT Library
+==================
+Python APT's library provides access to almost every functionality supported
+by the underlying apt-pkg and apt-inst libraries. This means that it is
+possible to rewrite frontend programs like apt-cdrom in Python, and this is
+relatively easy, as can be seen in e.g. :doc:`../tutorials/apt-cdrom`.
+
+When going through the library, the first two modules are :mod:`apt_pkg` and
+:mod:`apt_inst`. These modules are more or less straight bindings to the
+apt-pkg and apt-inst libraries and the base for the rest of python-apt.
+
+Going forward, the :mod:`apt` package appears. This package is using
+:mod:`apt_pkg` and :mod`apt_inst` to provide easy to use ways to manipulate
+the cache, fetch packages, or install new packages. It also provides useful
+progress classes, for text and GTK+ interfaces. The last package is
+:mod:`aptsources`. The aptsources package provides classes and functions to
+read files like :file:`/etc/apt/sources.list` and to modify them.
+
+.. toctree::
+    :maxdepth: 1
+
+    apt_pkg
+    apt_inst
+
+    apt.cache
+    apt.cdrom
+    apt.debfile
+    apt.package
+    apt.progress.text
+    apt.progress.gtk2
+    apt.progress.qt4
+
+    aptsources.distinfo
+    aptsources.distro
+    aptsources.sourceslist
+
diff --git a/doc/source/templates/indexcontent.html b/doc/source/templates/indexcontent.html
new file mode 100644
index 00000000..e5f11cc1
--- /dev/null
+++ b/doc/source/templates/indexcontent.html
@@ -0,0 +1,50 @@
+{% extends "defindex.html" %}
+{% block body %}
+  <h1>{{ docstitle|e }}</h1>
+  <p>
+    Welcome! This is
+    {% block description %}the documentation for {{ project|e }}
+    {{ release|e }}{% if last_updated %}, last updated {{ last_updated|e }}{% endif %}{% endblock %}.
+  </p>
+
+  <p>
+   This documentation has been created using Sphinx and reStructuredText files
+   written by Julian Andres Klode &lt;jak@debian.org&gt;.
+  </p>
+
+
+
+
+  <p><strong>Parts of the documentation:</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("whatsnew/" + version) }}">What's new in Python {{ version }}?</a><br/>
+         <span class="linkdescr">or <a href="{{ pathto("whatsnew/index") }}">all "What's new" documents</a></span></span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("library/index") }}">Library Reference</a><br/>
+         <span class="linkdescr">keep this under your pillow</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("tutorials/index") }}">Tutorials</a><br/>
+         <span class="linkdescr">examples and more...</span></p>
+    </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("c++/embedding") }}">Embedding</a><br/>
+         <span class="linkdescr">tutorial for C++ programmers</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("c++/api") }}">C++ API</a><br/>
+         <span class="linkdescr">reference for C++ programmers</span></p>
+    </td></tr>
+  </table>
+
+  <p><strong>Indices and tables:</strong></p>
+  <table class="contentstable" align="center"><tr>
+    <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Global Module Index</a><br/>
+         <span class="linkdescr">quick access to all modules</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
+         <span class="linkdescr">all functions, classes, terms</span></p>
+    </td><td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
+         <span class="linkdescr">search this documentation</span></p>
+      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Complete Table of Contents</a><br/>
+         <span class="linkdescr">lists all sections and subsections</span></p>
+    </td></tr>
+  </table>
+
+{% endblock %}
diff --git a/doc/source/templates/layout.html b/doc/source/templates/layout.html
new file mode 100644
index 00000000..60298719
--- /dev/null
+++ b/doc/source/templates/layout.html
@@ -0,0 +1,10 @@
+{% extends "!layout.html" %}
+{% block rootrellink %}
+        <li><img src="{{ pathto('_static/py.png', 1) }}" alt=""
+                 style="vertical-align: middle; margin-top: -1px"/></li>
+        <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li>
+{% endblock %}
+{% block extrahead %}
+    <link rel="shortcut icon" type="image/png" href="{{ pathto('_static/py.png', 1) }}" />
+{{ super() }}
+{% endblock %}
diff --git a/doc/source/tutorials/apt-cdrom.rst b/doc/source/tutorials/apt-cdrom.rst
new file mode 100644
index 00000000..c66d49f7
--- /dev/null
+++ b/doc/source/tutorials/apt-cdrom.rst
@@ -0,0 +1,156 @@
+Writing your own apt-cdrom
+==========================
+:Author: Julian Andres Klode <jak@debian.org>
+:Release: |release|
+:Date: |today|
+
+This article explains how to utilise python-apt to build your own clone of the
+:command:`apt-cdrom` command. To do this, we will take a look at the
+:mod:`apt.cdrom` and :mod:`apt.progress.text` modules, and we will learn how
+to use apt_pkg.parse_commandline to parse commandline arguments. The code shown
+here works on Python 2 and Python 3.
+
+Basics
+------
+The first step in building your own :command:`apt-cdrom` clone is to import the
+:mod:`apt` package, which will import :mod:`apt.cdrom` and
+:mod:`apt.progress.text`::
+
+    import apt
+
+Now we have to create a new :class:`apt.cdrom.Cdrom` object and pass to it an
+:class:`apt.progress.text.CdromProgress` object, which is responsible for
+displaying the progress and asking questions::
+
+    cdrom = apt.Cdrom(apt.progress.text.CdromProgress())
+
+Now we have to choose the action, depending on the given options on the
+command line. For now, we simply use the value of ``sys.argv[1]``::
+
+    import sys
+    if sys.argv[1] == 'add':
+        cdrom.add()
+    elif sys.argv[1] == 'ident':
+        cdrom.ident()
+
+Now we have a basic :command:`apt-cdrom` clone which can add and identify
+CD-ROMs::
+
+    import sys
+
+    import apt
+
+    cdrom = apt.Cdrom(apt.progress.text.CdromProgress())
+    if sys.argv[1] == 'add':
+        cdrom.add()
+    elif sys.argv[1] == 'ident':
+        cdrom.ident()
+
+Advcaned example with command-line parsing
+-------------------------------------------
+Our example clearly misses a way to parse the commandline in a correct
+manner. Luckily, :mod:`apt_pkg` provides us with a function to do this:
+:func:`apt_pkg.parse_commandline`. To use it, we add ``import apt_pkg`` right
+after import apt::
+
+    import sys
+
+    import apt_pkg
+    import apt
+
+
+:func:`apt_pkg.parse_commandline` is similar to :mod:`getopt` functions, it
+takes a list of recognized options and the arguments and returns all unknown
+arguments. If it encounters an unknown argument which starts with a leading
+'-', the function raises an error indicating that the option is unknown. The
+major difference is that this function manipulates the apt configuration space.
+
+The function takes 3 arguments. The first argument is an
+:class:`apt_pkg.Configuration` object. The second argument is a list of tuples
+of the form ``(shortopt, longopt, config, type)``, whereas *shortopt* is a
+character indicating the short option name, *longopt* a string indicating the
+corresponding long option (e.g. ``"--help"``), *config* the name of the
+configuration item which should be set and *type* the type of the argument.
+
+For apt-cdrom, we can use the following statement::
+
+    arguments = apt_pkg.parse_commandline(apt_pkg.config,
+                    [('h', "help", "help"),
+                     ('v', "version", "version"),
+                     ('d', "cdrom", "Acquire::cdrom::mount", "HasArg"),
+                     ('r', "rename", "APT::CDROM::Rename"),
+                     ('m', "no-mount", "APT::CDROM::NoMount"),
+                     ('f', "fast", "APT::CDROM::Fast"),
+                     ('n', "just-print", "APT::CDROM::NoAct"),
+                     ('n', "recon", "APT::CDROM::NoAct"),
+                     ('n', "no-act", "APT::CDROM::NoAct"),
+                     ('a', "thorough", "APT::CDROM::Thorough"),
+                     ('c', "config-file", "", "ConfigFile"),
+                     ('o', "option", "", "ArbItem")], args)
+
+
+This allows us to support all options supported by apt-cdrom. The first option
+is --help. As you can see, it omits the fourth field of the tuple; which means
+it is a boolean argument. Afterwards you could use
+``apt_pkg.config.find_b("help")`` to see whether ``--help`` was specified. In
+``('d',"cdrom","Acquire::cdrom::mount","HasArg")`` the fourth field is
+``"HasArg"``. This means that the option has an argument, in this case the
+location of the mount pint. ``('c',"config-file","","ConfigFile")`` shows how
+to include configuration files. This option takes a parameter which points to
+a configuration file which will be added to the configuration space.
+('o',"option","","ArbItem") is yet another type of option, which allows users
+to set configuration options on the commandline.
+
+Now we have to check whether help or version is specified, and print a message
+and exit afterwards. To do this, we use :meth:`apt_pkg.Configuration.find_b`
+which returns ``True`` if the configuration option exists and evaluates to
+``True``::
+
+    if apt_pkg.config.find_b("help"):
+        print("This should be a help message")
+        sys.exit(0)
+    elif apt_pkg.config.find_b("version"):
+        print("Version blah.")
+        sys.exit(0)
+
+
+Now we are ready to create our progress object and our cdrom object. Instead
+of using :class:`apt.Cdrom` like in the first example, we will use
+:class:`apt_pkg.Cdrom` which provides a very similar interface. We could also
+use :class:`apt.Cdrom`, but `apt.Cdrom` provides options like *nomount* which
+conflict with our commandline parsing::
+
+    progress = apt.progress.text.CdromProgress()
+    cdrom = apt_pkg.Cdrom()
+
+
+Now we have to do the action requested by the user on the commandline. To see
+which option was requested, we check the list ``arguments`` which was returned
+by ``apt_pkg.parse_commandline`` above, and afterwards call ``cdrom.add`` or
+``cdrom.ident``::
+
+    if apt_pkg.config.find_b("help"):
+        print("This should be a help message")
+        sys.exit(0)
+    elif apt_pkg.config.find_b("version"):
+        print("Version blah.")
+        sys.exit(0)
+
+    if not arguments:
+        sys.stderr.write('E: No operation specified\n')
+        sys.exit(1)
+    elif arguments[0] == 'add':
+        cdrom.add(progress)
+    elif arguments[0] == 'ident':
+        cdrom.ident(progress)
+    else:
+        sys.stderr.write('E: Invalid operation %s\n' % arguments[0])
+        sys.exit(1)
+
+
+After putting all our actions into a main() function, we get a completely
+working apt-cdrom clone, which just misses useful ``--help`` and ``--version``
+options. If we add a function show_help(), we get an even more complete
+apt-cdrom clone:
+
+.. literalinclude:: ../examples/apt-cdrom.py
diff --git a/doc/source/contributing.rst b/doc/source/tutorials/contributing.rst
index 7c6b6e6d..f68d626e 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/tutorials/contributing.rst
@@ -1,5 +1,9 @@
 Contributing to python-apt
 ==========================
+:Author: Julian Andres Klode <jak@debian.org>
+:Release: |release|
+:Date: |today|
+
 Let's say you need a new feature, you can develop it, and you want to get it
 included in python-apt. Then be sure to follow the following guidelines.
 
@@ -110,7 +114,7 @@ Code lay-out
     {
         int t_size = PyType_BASICSIZE(type);
         int b_size = PyType_BASICSIZE(base);
-    
+
         assert(t_size >= b_size); /* type smaller than base! */
         ...
         return 1;
diff --git a/doc/source/tutorials/index.rst b/doc/source/tutorials/index.rst
new file mode 100644
index 00000000..06d31c6b
--- /dev/null
+++ b/doc/source/tutorials/index.rst
@@ -0,0 +1,8 @@
+Tutorials
+=========
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *
diff --git a/doc/source/whatsnew/0.8.0.rst b/doc/source/whatsnew/0.8.0.rst
index 244da388..8a2b52e8 100644
--- a/doc/source/whatsnew/0.8.0.rst
+++ b/doc/source/whatsnew/0.8.0.rst
@@ -78,11 +78,13 @@ Yet another context manager is available for locking the package system::
 
     with apt_pkg.SystemLock():
         # do your stuff here
+        pass
 
-There is also one for file based locking:
+There is also one for file based locking::
 
     with apt_pkg.FileLock(filename):
         # do your stuff here
+        pass
 
 
 Unification of dependency handling