Merge lp:~renamer-developers/renamer/documentation into lp:renamer

[Jonathan Jacobs]

Move to using Sphinx for documentation purposes. HTML versions of the documentation are conveniently available for proofreading at <http://slipgate.za.net/~korpse/docs/Renamer/current/html/>

[lp:~renamer-developers/renamer/documentation]

132. By Jonathan Jacobs on 2010-10-31

Merge trunk.

[Jonathan Jacobs (jjacobs)]

Conflicts between this branch and trunk have been resolved.

[lp:~renamer-developers/renamer/documentation]

133. By Jonathan Jacobs on 2010-11-01

Merge trunk.

[Tristan Seligmann (mithrandi)]

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2009-05-07 10:45:13 +0000
+++ .bzrignore	2010-11-01 08:51:04 +0000
@@ -1,1 +1,2 @@
 dropin.cache
+_build
 
=== added file 'docs/Makefile'
--- docs/Makefile	1970-01-01 00:00:00 +0000
+++ docs/Makefile	2010-11-01 08:51:04 +0000
@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         = a4
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.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 "  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 manual 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 $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+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) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Renamer.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Renamer.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/Renamer"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Renamer"
+	@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) $(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) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
 
=== added directory 'docs/code'
=== added file 'docs/code/plugins_command.py'
--- docs/code/plugins_command.py	1970-01-01 00:00:00 +0000
+++ docs/code/plugins_command.py	2010-11-01 08:51:04 +0000
@@ -0,0 +1,42 @@
+import os
+import string
+import time
+
+from renamer.plugin import RenamingCommand
+from renamer.errors import PluginError
+
+
+class ReadableTimestamps(RenamingCommand):
+    # The name of our command, as it will be used from the command-line.
+    name = 'timestamp'
+
+    # A brief description of the command's purpose, displayed in --help output.
+    description = 'Rename files with POSIX timestamps to human-readble times.'
+
+    # Command-line parameters we support.
+    optParameters = [
+        ('format', 'f', '%Y-%m-%d %H-%M-%S', 'strftime format.')]
+
+    # The default name template to use if no name template is specified via the
+    # command-line or configuration file.
+    defaultNameTemplate = string.Template('$time')
+
+    # IRenamerCommand
+
+    def processArgument(self, arg):
+        # The extension is not needed as it will be determined from the
+        # original file name.
+        name, ext = arg.splitext()
+        try:
+            # Try convert the filename to a floating point number.
+            timestamp = float(name)
+        except (TypeError, ValueError):
+            # If it is not a floating point number then we raise an exception
+            # to stop the process.
+            raise PluginError('%r is not a valid timestamp' % (name,))
+        else:
+            # Convert and format the timestamp according to the "format"
+            # command-line parameter.
+            t = time.localtime(timestamp)
+            return {
+                'time': time.strftime(self['format'], t)}
 
=== added file 'docs/conf.py'
--- docs/conf.py	1970-01-01 00:00:00 +0000
+++ docs/conf.py	2010-11-01 08:51:04 +0000
@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+#
+# Renamer documentation build configuration file, created by
+# sphinx-quickstart on Thu Oct 21 09:53:03 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.coverage']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Renamer'
+copyright = u'2010, Jonathan Jacobs, Tristan Seligmann, Andrew Snowden'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.1.0'
+# The full version, including alpha/beta/rc tags.
+release = '0.1.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+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'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'Renamerdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'Renamer.tex', u'Renamer Documentation',
+   u'Jonathan Jacobs, Tristan Seligmann, Andrew Snowden', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('manual', 'rn', u'an extensible mass file renamer',
+     [u'Jonathan Jacobs', u'Tristan Seligmann', u'Andrew Snowden'], 1)
+]
 
=== added file 'docs/index.rst'
--- docs/index.rst	1970-01-01 00:00:00 +0000
+++ docs/index.rst	2010-11-01 08:51:04 +0000
@@ -0,0 +1,16 @@
+Renamer |version| documentation
+===============================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   manual
+   plugins
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
 
=== added file 'docs/make.bat'
--- docs/make.bat	1970-01-01 00:00:00 +0000
+++ docs/make.bat	2010-11-01 08:51:04 +0000
@@ -0,0 +1,155 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	: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.  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.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  changes    to make an overview over 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
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Renamer.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Renamer.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end
 
=== added file 'docs/manual.rst'
--- docs/manual.rst	1970-01-01 00:00:00 +0000
+++ docs/manual.rst	2010-11-01 08:51:04 +0000
@@ -0,0 +1,247 @@
+.. index:: manual, rn
+
+Renamer manual
+==============
+
+========
+SYNOPSIS
+========
+
+rn [*options*] command [*options*] argument ...
+
+
+===========
+DESCRIPTION
+===========
+
+**rn** is a command line interface to Renamer, an extensible utility for
+renaming files that also keeps a log of previous activities, which allows
+actions to be reversed.
+
+The required *command* argument selects which renamer command to execute. Most,
+but not all, commands invoke the renaming process on the provided arguments,
+the :ref:`undo` command is one example that differs. Consult ``--help`` for a
+list of available commands and the :ref:`COMMANDS` section for descriptions of
+the builtin commands.
+
+Renamer can be extended with new commands via Python plugins.
+
+
+=======
+OPTIONS
+=======
+
+-g, --glob
+    Expand arguments as UNIX-style globs.
+
+-x, --one-file-system
+    Don't cross filesystems. This is primarily useful for avoiding copy-delete
+    behavior when renaming will cross file-system boundaries.
+
+-n, --no-act
+    Perform a trial run with no changes made.
+
+--link-src
+    Create a symlink at the source. The file will be moved to its new location
+    and a symlink created at its original location.
+
+--link-dst
+    Create a symlink at the destination. The original file will not be moved
+    but a symlink will be created at the new location.
+
+-c file, --config=file
+    Read configuration defaults from *file*. The default configuration is read
+    from *~/.renamer/renamer.conf*. See the :ref:`CONFIGURATION` section for
+    more information.
+
+-e template, --name=template
+    Formatted filename. See the :ref:`TEMPLATES` section for more information.
+
+-p template, --prefix=template
+    Formatted path to prefix to files before renaming. See the :ref:`TEMPLATES`
+    section for more information.
+
+-l number, --concurrent=number
+    Maximum number of asynchronous tasks to perform concurrently. The default
+    is 10.
+
+--help
+    Display a help message describing Renamer's command-line options.
+
+-q, --quiet
+    Suppress output.
+
+--version
+    Display version information.
+
+-v, --verbose
+    Increase output, use more times for greater effect.
+
+
+.. index:: commands
+
+.. _commands:
+
+========
+COMMANDS
+========
+
+Commands are the parts of Renamer that process arguments and make things
+happen. Most commands will extract metadata from each argument in some fashion
+and store that metadata in template variables which is used to rename the
+files.
+
+.. index:: tvrage
+
+.. _tvrage:
+
+tvrage
+------
+
+--series
+    Override the series name metadata.
+
+--season
+    Override the season number metadata.
+
+--episode
+    Override the episode number metadata.
+
+Use TV episode metadata from filenames (such as ``Lost S01E01.avi``) to consult
+the `TV Rage`_ database for detailed and accurate metadata used in renaming.
+
+.. _TV Rage: http://tvrage.com/
+
+Renamer is able to extract metadata from a wide variety of filename structures.
+Unfortunately, since useful metadata within the video container itself is
+extremely rare, the only reliable way to extract information is from the
+filename, meaning that filenames should be as clear as possible and contain as
+much useful metadata as possible.
+
+In the event a filename does not contain enough information to determine a
+name, season and episode number you can use the override command-line options
+``--series``, ``--season`` and ``--episode``. Specifying any one of these will
+accomplish two things:
+
+1. Override any detected metadata in the filename for that particular
+   component, and;
+
+2. Relax the filename detection techniques so that less specific filenames can
+   match when there is enough combined metadata between filenames and
+   overrides. For example: A file named ``House - 1.avi`` combined with
+   ``--season=2`` means that there is enough metadata to look up information
+   for the *first* episode of the *second* season of the show "House".
+
+
+.. index:: audio
+
+.. _audio:
+
+audio
+-----
+
+Use audio metadata from files for renaming. A wide variety of audio and audio
+metadata formats are supported.
+
+
+.. index:: undo
+
+.. _undo:
+
+undo
+----
+
+--ignore-errors
+    Do not stop the process when encountering OS errors.
+
+
+Undo previous Renamer actions.
+
+The ``action`` subcommand will undo individual actions while the ``changeset``
+subcommand will undo entire changesets, once an item has been undone it is
+removed from the history. The ``forget`` subcommand will remove an item from
+history without undoing it.
+
+Use the ``list`` subcommand to find identifiers for the changesets or actions
+to undo.
+
+
+.. index:: templates
+
+.. _templates:
+
+=========
+TEMPLATES
+=========
+
+A Python template string, as described by the Python `template documentation`_,
+can contain variables that will be substituted with runtime values from Renamer
+commands.
+
+.. _template documentation:
+    http://docs.python.org/library/string.html#template-strings
+
+For example the :ref:`tvrage` command provides variables containing TV episode
+metadata; so a template such as::
+
+    $series S${padded_season}E${padded_episode} - $title
+
+Applied to episode 1 of season 1 of "Lost" (named "Pilot (1)") will result in::
+
+    Lost S01E01 - Pilot (1)
+
+The variables available will differ from command to command, consult the
+``--help`` output for the command to learn more.
+
+
+.. index:: configuration, config file
+
+.. _configuration:
+
+=============
+CONFIGURATION
+=============
+
+Configuration files follow a basic INI syntax. Sections are named after their
+command names, as listed in ``--help``, the global configuration section is
+named ``renamer``. Configuration options are derived from their long
+command-line counterparts without the ``--`` prefix. Flags can be turned on or
+off with values such as: ``true``, ``yes``, ``1``, ``false``, ``no``, ``0``.
+
+For example the command line::
+
+    rn --concurrent=5 --link-src --prefix=~/stuff somecommand --no-thing
+
+can be specified in a configuration file::
+
+    [renamer]
+    concurrent=5
+    link-src=yes
+    prefix=~/stuff
+
+    [somecommand]
+    no-thing=yes
+
+It is also possible to specify global configuration options in a command
+section to override them only for that specific command.
+
+Arguments specified on the command line will override values in the
+configuration file.
+
+
+====
+BUGS
+====
+
+Please report any bugs to the `Renamer Launchpad project`_
+``<http://launchpad.net/renamer/>``.
+
+.. _Renamer Launchpad project: http://launchpad.net/renamer/
+
+
+=====
+FILES
+=====
+
+~/.renamer/renamer.conf
+    Contains the user's default configuration.
 
=== added file 'docs/plugins.rst'
--- docs/plugins.rst	1970-01-01 00:00:00 +0000
+++ docs/plugins.rst	2010-11-01 08:51:04 +0000
@@ -0,0 +1,134 @@
+.. index:: plugins
+
+Creating a Renamer Plugin
+=========================
+
+Introduction
+------------
+
+Renamer plugins are Python code, discovered by Twisted's `plugin
+system`_, that extends Renamer's functionality without having to modify the
+core of Renamer.
+
+.. _plugin system:
+    http://twistedmatrix.com/documents/current/core/howto/plugin.html
+
+There are two kinds of pluggable code in Renamer:
+
+1. Commands that perform actions unrelated to directly renaming a file. An
+   example of this would be the `undo` command.
+
+2. Renaming commands that determine new filenames from existing files and
+   ultimately result in an input being renamed. An example of this would be the
+   :ref:`tvrage` command.
+
+Since the topic of creating commands that are not directly related to renaming
+is so broad, this document will primarily focus on creating a command that
+performs renaming.
+
+
+Foundations
+-----------
+
+Renamer commands are simply Twisted `Options`_ subclasses with a few extra bits
+thrown in, so all the usual Options attributes (such as ``optParameters``) are
+available for use and should be how you expose additional options for your
+command.
+
+.. _Options:
+    http://twistedmatrix.com/documents/current/core/howto/options.html
+
+In almost all cases you will want to inherit from the ``RenamingCommand`` base
+class, as it ensure your subclass provides all the right interfaces as well as
+invoking your command and performing the actual file renaming.
+
+At the heart of a renaming command is ``processArgument`` which accepts one
+argument and returns a Python dictionary. That dictionary is then used to
+perform `template substitution`_ on the ``name`` and ``prefix`` command-line
+options (or, if they're not given, command-specific defaults.) This process of
+calling ``processArgument`` is repeated for each argument given, letting your
+command process one argument at a time.
+
+.. _template substitution:
+    http://docs.python.org/library/string.html#template-strings
+
+
+Deferreds
+---------
+
+If your command performs a long-running task, such as fetching data from a web
+server, you can return a `Deferred`_ from ``processArgument`` that should
+ultimately return with a Python dictionary to be used in assembling the
+destination filename.
+
+.. _Deferred:
+    http://twistedmatrix.com/documents/current/core/howto/deferredindepth.html
+
+
+Sample command
+--------------
+
+Below is the complete source code of a command that renames files named as
+POSIX timestamps (e.g. ``1287758780.4690211.txt``) to a human-readable
+representation of the timestamp (e.g. ``2010-10-22 16-46-20.txt``).
+
+.. literalinclude:: code/plugins_command.py
+   :linenos:
+
+
+Installing the plugin
+---------------------
+
+Now that we've constructed our command we need to make it available to Renamer.
+This process consists of the following simple steps:
+
+1. Create a directory for your plugins such as ``MyRenamerPlugins`` wherever you
+   usually put your source code, beneath this create a directory named
+   ``renamer`` and beneath that a directory named ``plugins``.
+
+   Your directory tree should look like::
+
+        .
+        |-- MyRenamerPlugins
+        |   `-- renamer
+        |   |   `-- plugins
+
+2. Add your directory (``MyRenamerPlugins`` in the previous step) to sys.path
+   (typically by adding it to the PYTHONPATH environment variable.)
+
+3. Put your plugin source code file (with a ``.py`` extension) in the
+   ``MyRenamerPlugins/renamer/plugins`` directory. It is important to note that
+   this directory must **not** be a Python package (i.e. it must not contain
+   ``__init__.py``) and will be skipped (i.e. no plugins will be loaded) if it is
+   one.
+
+4. You can verify that your plugin is visible by running an interactive Python
+   prompt and doing something similar to::
+
+       >>> from renamer.plugins.timestamp import ReadableTimestamps
+       >>>
+
+   (This obviously assumes that you used the ``ReadableTimestamps`` example and
+   stored it in a file called ``timestamp.py``.)
+
+   If your plugin is installed correctly there should be no errors importing
+   the module.
+
+
+Using the plugin
+----------------
+
+After your plugin has been installed correctly you can use it::
+
+    $ touch 1287758780.4690211.txt
+    $ rn timestamp 1287758780.4690211.txt
+    $ ls
+    2010-10-22 16-46-20.txt
+
+It is possible that you may need to regenerate the Twisted plugin cache if you
+notice nonsensical errors related to your plugin objects, especially if you're
+actively developing a plugin and testing it. Refer to the Twisted documentation
+regarding `plugin caching`_.
+
+.. _plugin caching:
+    http://twistedmatrix.com/documents/current/core/howto/plugin.html#auto3
 
=== removed file 'docs/rn.1'
--- docs/rn.1	2009-05-06 10:15:24 +0000
+++ docs/rn.1	1970-01-01 00:00:00 +0000
@@ -1,93 +0,0 @@
-.TH RN 1 2009-05-04 "version 1.0.0" "USER COMMANDS"
-
-.SH NAME
-rn \- scriptable and extensible mass file renamer
-
-.SH SYNOPSYS
-.B rn
-.RB [\| \-g \|]
-.RB [\| \-m \|]
-.RB [\| \-R \|]
-.RB [\| \-s
-.IR file \|]
-.RB [\| \-S
-.IR sort \|]
-.RB [\| \-t \|]
-.RB [\| \-q \|]
-.RB [\| \-v \|]
-.RI [\| argument \|]
-\&\.\.\.
-
-.SH DESCRIPTION
-.B rn
-is a command line interface to Renamer, a utility designed to rename files
-according to a set of user-provided instructions, generally residing in a
-script file.
-
-.SH OPTIONS
-If no arguments are provided,
-.B rn
-is invoked in interactive mode.
-.TP
-.B \-g, \-\-glob
-Expand arguments according to UNIX-style globs.
-.TP
-.B \-m, \-\-move
-Enable \(lqmove mode\(rq, this allows scripts to perform file move operations.
-.TP
-.B \-R, \-\-reverse
-Reverse the sorting order of the arguments.
-.TP
-.BI \-s\  file ,\ \-\-script= file
-Execute
-.I file\c
-, as a script, for each argument. Each argument is invoked in its own script
-environment, meaning that the stack is not retained between executions and
-any stored variables are not persisted.
-.TP
-.BI \-S\  sort ,\ \-\-sort= sort
-Sort arguments according to criteria:
-.BR name , \ size , \ time .
-.TP
-.B \-t, \-\-dry-run
-Perform a dry-run, meaning that no permanent operations are performed, such
-as file renaming.
-.TP
-.B \-q, \-\-quiet
-Reduce verbosity level.
-.TP
-.B \-v, \-\-verbose
-Increase verbosity level.
-
-.SH SCRIPTING
-Renamer operates in a stack based environment. Command line arguments,
-function return values and function parameters are all pushed and popped
-from the stack.
-.PP
-Function arguments are an exception: any arguments passed inline to a function
-are subtracted from the total number of arguments required and appended to
-the arguments popped from the stack. For example:
-.PP
-.nf
-rn> push "foo bar baz"
-rn> split " "
-rn> stack
---> ['foo', 'bar', 'baz']
-.fi
-.PP
-Renamer's interactive mode should prove valuable in exploring the behaviour
-of Renamer's commands, particularly the
-.I help
-and
-.I commands
-functions.
-
-.SH FILES
-.TP
-.I ~/.renamer/scripts/
-Directory containing user-provided scripts
-.TP
-.I ~/.renamer/plugin_name/config
-Config file for configuring
-.B plugin_name
-individually
 
=== added directory 'docs/static'
=== added directory 'docs/templates'
=== modified file 'renamer/plugins/undo.py'
--- renamer/plugins/undo.py	2010-10-24 17:46:32 +0000
+++ renamer/plugins/undo.py	2010-11-01 08:51:04 +0000
@@ -27,7 +27,7 @@
 
 class _UndoMixin(object):
     optFlags = [
-        ('ignore-errors', None, 'Do not stop the process when encountering OS errors')]
+        ('ignore-errors', None, 'Do not stop the process when encountering OS errors.')]
 
 
     def undoActions(self, options, changeset, actions):