Anonymous avatar Anonymous committed 3a032b1

[svn] Expand the quickstart a bit.

Comments (0)

Files changed (2)

docs/src/index.txt

 
   - `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>`_
+
+  - `Builtin tokens <tokens.txt>`_
 
   - `API documentation <api.txt>`_
 
-  - `Builtin Tokens <tokens.txt>`_
-
 - Hacking for Pygments
 
   - `Write your own lexer <lexerdevelopment.txt>`_
   
   - `Write your own filter <filterdevelopment.txt>`_
 
-  - `Register Plugins <plugins.txt>`_
+  - `Register plugins <plugins.txt>`_
 
 - Hints and Tricks
 

docs/src/quickstart.txt

 .. -*- 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
 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
 ==========================
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.