Add api, command line, etc. documentation for custom lexer/formatter loading

3 files changed, 54 insertions, 4 deletions

diff --git a/doc/docs/api.rst b/doc/docs/api.rst
index 1b6ca668..ea158d65 100644
--- a/doc/docs/api.rst
+++ b/doc/docs/api.rst
@@ -71,8 +71,12 @@ Functions from :mod:`pygments.lexers`:
     The lexer is given the `options` at its instantiation.
 
     :exc:`IOError` is raised if the file is not found or unreadable
+
     :exc:`ImportError` is raised if the file doesn't have a CustomLexer class
-    :exc:`Exception` for any other error raised when evaluating filename
+
+    Additionally, arbitrary exceptions could occur when evaluating the file
+
+    .. versionadded:: ?
 
 .. function:: guess_lexer(text, **options)
 
@@ -146,9 +150,12 @@ Functions from :mod:`pygments.formatters`:
     The formatter is given the `options` at its instantiation.
 
     :exc:`IOError` is raised if the file is not found or unreadable
+
     :exc:`ImportError` is raised if the file doesn't have a CustomFormatter class
-    :exc:`Exception` for any other error raised when evaluating filename
 
+    Additionally, arbitrary exceptions could occur when evaluating the file
+
+    .. versionadded:: ?
 
 .. module:: pygments.styles
 
diff --git a/doc/docs/cmdline.rst b/doc/docs/cmdline.rst
index 165af969..8fcd3c8c 100644
--- a/doc/docs/cmdline.rst
+++ b/doc/docs/cmdline.rst
@@ -99,6 +99,19 @@ The ``-N`` option guesses a lexer name for a given filename, so that ::
 will print out ``python``.  It won't highlight anything yet.  If no specific
 lexer is known for that filename, ``text`` is printed.
 
+Custom Lexers and Formatters
+----------------------------
+
+.. versionadded:: ?
+
+The ``--load-from-file`` flag enables custom lexers and formatters to be loaded
+from files relative to the current directory. Create a file with a class named
+CustomLexer or CustomFormatter, then specify it on the command line::
+
+    $ pygmentize -l your_lexer.py -f your_formatter.py --load-from-file
+
+For more information, see :doc:`the Pygments documentation on Lexer development
+<lexerdevelopment>`.
 
 Getting help
 ------------
diff --git a/doc/docs/lexerdevelopment.rst b/doc/docs/lexerdevelopment.rst
index 2c868440..8c9b7baa 100644
--- a/doc/docs/lexerdevelopment.rst
+++ b/doc/docs/lexerdevelopment.rst
@@ -88,8 +88,38 @@ one.
 Adding and testing a new lexer
 ==============================
 
-To make Pygments aware of your new lexer, you have to perform the following
-steps:
+The easiest way to use a new lexer is to use Pygments' support for loading
+the lexer from a file relative to your current directory.
+
+First, change the name of your lexer class to CustomLexer:
+
+.. code-block:: python
+
+    from pygments.lexer import RegexLexer
+    from pygments.token import *
+
+    class CustomLexer(RegexLexer):
+        """All your lexer code goes here!"""
+
+Then you can load the lexer from the command line with the additional
+flag ``--load-from-file``:
+
+.. code-block:: console
+
+    $ pygmentize -l your_lexer_file.py --load-from-file
+
+Or, using the Python API:
+
+.. code-block:: python
+
+    your_lexer = load_lexer_from_file(filename, **options)
+
+When loading custom lexers and formatters, be extremely careful to use only
+trusted files; Pygments will perform the equivalent of ``eval`` on them.
+
+For more complicated tasks, you should add your lexer to Pygments. If you
+want to make Pygments aware of your new lexer, you have to perform the
+following steps:
 
 First, change to the current directory containing the Pygments source code: