[svn] Expand the quickstart a bit.

2 files changed, 43 insertions, 16 deletions

diff --git a/docs/src/index.txt b/docs/src/index.txt
index 3676f6c7..957822d2 100644
--- a/docs/src/index.txt
+++ b/docs/src/index.txt
@@ -10,27 +10,27 @@ Welcome to the Pygments documentation.
 
   - `Installation <installation.txt>`_
 
-  - `Quickstart <quickstart.txt>`_
+  - `Introduction and Quickstart <quickstart.txt>`_
 
   - `Command line interface <cmdline.txt>`_
 
-- Essential to know
+- Builtin components
 
-  - `Builtin lexers <lexers.txt>`_
+  - `Lexers <lexers.txt>`_
 
-  - `Builtin formatters <formatters.txt>`_
+  - `Formatters <formatters.txt>`_
 
   - `Filters <filters.txt>`_
 
   - `Styles <styles.txt>`_
 
-  - `Unicode <unicode.txt>`_
+- Reference
 
-- API and more
+  - `Unicode and encodings <unicode.txt>`_
 
-  - `API documentation <api.txt>`_
+  - `Builtin tokens <tokens.txt>`_
 
-  - `Builtin Tokens <tokens.txt>`_
+  - `API documentation <api.txt>`_
 
 - Hacking for Pygments
 
@@ -40,7 +40,7 @@ Welcome to the Pygments documentation.
   
   - `Write your own filter <filterdevelopment.txt>`_
 
-  - `Register Plugins <plugins.txt>`_
+  - `Register plugins <plugins.txt>`_
 
 - Hints and Tricks
 
diff --git a/docs/src/quickstart.txt b/docs/src/quickstart.txt
index 489c6112..93f32c0f 100644
--- a/docs/src/quickstart.txt
+++ b/docs/src/quickstart.txt
@@ -1,14 +1,30 @@
 .. -*- mode: rst -*-
 
-==========
-Quickstart
-==========
+===========================
+Introduction and 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
-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.
+Welcome to Pygments! This document explains the basic concepts and terms and
+gives a few examples of how to use the library.
+
+
+Architecture
+============
+
+There are four types of components that work together highlighting a piece of
+code:
+
+* A **lexer** splits the source into tokens, fragments of the source that
+  have a token type that determines what the text represents semantically
+  (e.g., keyword, string, or comment). There is a lexer for every language
+  or markup format that Pygments supports.
+* The token stream can be piped through **filters**, which usually modify
+  the token types or text fragments, e.g. uppercasing all keywords.
+* A **formatter** then takes the token stream and writes it to an output
+  file, in a format such as HTML, LaTeX or RTF.
+* While writing the output, a **style** determines how to highlight all the
+  different token types. It maps them to attributes like "red and bold".
 
 
 Example
@@ -77,9 +93,20 @@ This makes the lexer strip all leading and trailing whitespace from the input
 and sets the wrapping ``<div>``'s class to ``source`` (instead of
 ``highlight``).
 
+Important options include:
+
+`encoding` : for lexers and formatters
+   Since Pygments uses Unicode strings internally, this determines which
+   encoding will be used to convert to or from byte strings.
+`style` : for formatters
+   The name of the style to use when writing the output.
+
+
 For an overview of builtin lexers and formatters and their options, visit the
 `lexer <lexers.txt>`_ and `formatters <formatters.txt>`_ lists.
 
+For a documentation on filters, see `this page <filters.txt>`_.
+
 
 Lexer and formatter lookup
 ==========================