[svn] Smartify pygmentize encoding handling.

2 files changed, 26 insertions, 4 deletions

diff --git a/docs/src/cmdline.txt b/docs/src/cmdline.txt
index 494b0c5e..7e5143fa 100644
--- a/docs/src/cmdline.txt
+++ b/docs/src/cmdline.txt
@@ -81,4 +81,24 @@ will print the help for the HTML formatter, while ::
 will print the help for the Python lexer, etc.
 
 
+A note on encodings
+-------------------
+
+Pygments tries to be smart regarding encodings in the formatting process:
+
+* If you give an ``encoding`` option, it will be used as the input and
+  output encoding.
+
+* If you give an ``outencoding`` option, it will override ``encoding``
+  as the output encoding.
+
+* If you don't give an encoding and have given an output file, the default
+  encoding for lexer and formatter is ``latin1`` (which will pass through
+  all non-ASCII characters).
+
+* If you don't give an encoding and haven't given an output file (that means
+  output is written to the console), the default encoding for lexer and
+  formatter is the terminal encoding (`sys.stdout.encoding`).
+
+
 .. _a particular formatter: formatters.txt
diff --git a/docs/src/unicode.txt b/docs/src/unicode.txt
index 8184e2b2..dc6394a9 100644
--- a/docs/src/unicode.txt
+++ b/docs/src/unicode.txt
@@ -34,10 +34,12 @@ source and the output stream does not accept Unicode written to it!**
 This is the case for all regular files and for terminals.
 
 Note: The Terminal formatter tries to be smart: if its output stream has an
-`encoding` attribute, and you haven't set the option,
-it will encode any Unicode string with this encoding
-before writing it. This is the case for `sys.stdout`, for example. The other
-formatters don't have that behavior.
+`encoding` attribute, and you haven't set the option, it will encode any
+Unicode string with this encoding before writing it. This is the case for
+`sys.stdout`, for example. The other formatters don't have that behavior.
+
+Another note: If you call Pygments via the command line (`pygmentize`),
+encoding is handled differently, see `the command line docs <cmdline.txt>`_.
 
 *New in Pygments 0.7*: the formatters now also accept an `outencoding` option
 which will override the `encoding` option if given. This makes it possible to