gbrandl  committed 3a032b1

[svn] Expand the quickstart a bit.

  • Participants
  • Parent commits d44d054
  • Branches trunk

Comments (0)

Files changed (2)

File 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

File docs/src/quickstart.txt

 .. -*- mode: rst -*-
+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.
+There are four types of components that work together highlighting a piece of
+* 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".
 and sets the wrapping ``<div>``'s class to ``source`` (instead of
+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