[svn] Fix a few inconsistencies and nits, mainly in the docs.

Use the get_choice_opt function consistently.

4 files changed, 49 insertions, 23 deletions

diff --git a/docs/src/api.txt b/docs/src/api.txt
index 8cd7f1f2..ba581306 100644
--- a/docs/src/api.txt
+++ b/docs/src/api.txt
@@ -158,15 +158,15 @@ def `analyze_text(text):`
 
 For a list of known tokens have a look at the `Tokens`_ page.
 
-The lexer also recognizes the following attributes that are used by the
-builtin lookup mechanism.
+A lexer also can have the following attributes (in fact, they are mandatory
+except `alias_filenames`) that are used by the builtin lookup mechanism.
 
 `name`
     Full name for the lexer, in human-readable form.
 
 `aliases`
     A list of short, unique identifiers that can be used to lookup
-    the lexer from a list.
+    the lexer from a list, e.g. using `get_lexer_by_name()`.
 
 `filenames`
     A list of `fnmatch` patterns that match filenames which contain
@@ -222,6 +222,21 @@ def `format(self, tokensource, outfile):`
 
 .. _command-line option: cmdline.txt
 
+A formatter must have the following attributes that are used by the
+builtin lookup mechanism. (*New in Pygments 0.7.*)
+
+`name`
+    Full name for the formatter, in human-readable form.
+
+`aliases`
+    A list of short, unique identifiers that can be used to lookup
+    the formatter from a list, e.g. using `get_formatter_by_name()`.
+
+`filenames`
+    A list of `fnmatch` patterns that match filenames for which this formatter
+    can produce output. The patterns in this list should be unique among
+    all formatters.
+
 
 Option processing
 =================
@@ -231,7 +246,7 @@ processing:
 
 class `OptionError`
     This exception will be raised by all option processing functions if
-    the type of the argument is not correct.
+    the type or value of the argument is not correct.
 
 def `get_bool_opt(options, optname, default=None):`
     Interpret the key `optname` from the dictionary `options`
@@ -249,3 +264,7 @@ def `get_list_opt(options, optname, default=None):`
     If the key `optname` from the dictionary `options` is a string,
     split it at whitespace and return it. If it is already a list
     or a tuple, it is returned as a list.
+
+def `get_choice_opt(options, optname, allowed, default=None):`
+    If the key `optname` from the dictionary is not in the sequence
+    `allowed`, raise an error, otherwise return it. *New in Pygments 0.8.*
diff --git a/docs/src/lexers.txt b/docs/src/lexers.txt
index 22fe7c7a..5d40b4b8 100644
--- a/docs/src/lexers.txt
+++ b/docs/src/lexers.txt
@@ -31,12 +31,15 @@ Currently, **all lexers** support these options:
     guess the encoding of the input.
 
 
+The "Short Names" field lists the identifiers that can be used with the
+`get_lexer_by_name()` function.
+
 These lexers are builtin and can be imported from `pygments.lexers`:
 
 [builtin_lexer_docs]
 
 Iterating over all lexers
-=========================
+-------------------------
 
 *New in Pygments 0.6.*
 
diff --git a/docs/src/plugins.txt b/docs/src/plugins.txt
index da8b33b9..2c98c523 100644
--- a/docs/src/plugins.txt
+++ b/docs/src/plugins.txt
@@ -2,32 +2,35 @@
 Register Plugins
 ================
 
-If you want to extend pygments without hacking in the sources but want to
-use the lexer/formatter/style resolve functions you can use setuptools
-entrypoints to add new lexers, formatters or styles to the pygments core.
+If you want to extend Pygments without hacking the sources, but want to
+use the lexer/formatter/style/filter lookup functions (`lexers.get_lexer_by_name`
+et al.), you can use `setuptools`_ entrypoints to add new lexers, formatters
+or styles as if they were in the Pygments core.
 
-That means you can use your highlighter also with the ``pygmentize`` script.
+.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools
+
+That means you can use your highlighter modules with the `pygmentize` script,
+which relies on the mentioned functions.
 
 
 Entrypoints
 ===========
 
-Here a list of setuptools entrypoints pygments understands:
+Here is a list of setuptools entrypoints that Pygments understands:
 
 `pygments.lexers`
 
-    This entrypoint is used for adding new lexers to the pygments core.
-    The name of entrypoint values doesn't really matter, pygements extract
-    required informations from the class definition:
+    This entrypoint is used for adding new lexers to the Pygments core.
+    The name of the entrypoint values doesn't really matter, Pygments extracts
+    required metadata from the class definition:
 
     .. sourcecode:: ini
 
         [pygments.lexers]
         yourlexer = yourmodule:YourLexer
 
-    Note that you have to
-    defined a ``name``, ``aliases`` and ``filename`` patterns so that you
-    can use the highlighter from the command line:
+    Note that you have to define ``name``, ``aliases`` and ``filename``
+    attributes so that you can use the highlighter from the command line:
 
     .. sourcecode:: python
 
@@ -39,9 +42,9 @@ Here a list of setuptools entrypoints pygments understands:
 
 `pygments.formatters`
 
-    You can use this entrypoint to add new formatters to pygments. The
+    You can use this entrypoint to add new formatters to Pygments. The
     name of an entrypoint item is the name of the formatter. If you
-    prefix the name with a slash it's used for the filename pattern:
+    prefix the name with a slash it's used as a filename pattern:
 
     .. sourcecode:: ini
 
@@ -86,5 +89,6 @@ you need to write a plugin. Also `this blog entry`_ might be interesting.
 Extending The Core
 ==================
 
-If you have written a pygments plugin which is open source, please inform us
-about that. There is a high chance that we'll add it to the pygments core :-)
+If you have written a Pygments plugin that is open source, please inform us
+about that. There is a high chance that we'll add it to the Pygments
+distribution.
diff --git a/docs/src/quickstart.txt b/docs/src/quickstart.txt
index 91e0953f..489c6112 100644
--- a/docs/src/quickstart.txt
+++ b/docs/src/quickstart.txt
@@ -6,9 +6,9 @@ Quickstart
 
 
 Pygments comes with a wide range of lexers for modern languages which are all
-accessible through the pygments.lexers package. A lexer enables Pygments to
-parse the source code into tokens which then are passed to a formatter. Currently
-formatters exist for HTML, LaTeX, RTF and ANSI sequences.
+accessible through the `pygments.lexers` package. A lexer enables Pygments to
+split the source code into tokens which then are passed to a formatter.
+The most useful formatters include HTML, LaTeX, RTF and ANSI sequence output.
 
 
 Example