From ec46692cf5c4d5e22950bc8e7d14cb0ec327fb87 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan@gmail.com>
Date: Wed, 7 Mar 2012 09:35:40 -0500
Subject: Rename docs/*.md => docs/*.txt

The documentation uses features of Python-Markdown that are not supported on
GitHub and it's better to get a source view of the docs anyway. For example,
that way comments and bug reports can reference a specific line of a file.

Of course, it makes sense for Github to render the README, so that is left
with the `.md` file extension.
---
 docs/extensions/code_hilite.txt | 126 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)
 create mode 100644 docs/extensions/code_hilite.txt

(limited to 'docs/extensions/code_hilite.txt')

diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt
new file mode 100644
index 0000000..aa0fe57
--- /dev/null
+++ b/docs/extensions/code_hilite.txt
@@ -0,0 +1,126 @@
+title:      CodeHilite Extension
+prev_title: Smart Strong Extension
+prev_url:   smart_strong.html
+next_title: HTML Tidy Extension
+next_url:   html_tidy.html
+
+CodeHilite
+==========
+
+Summary
+-------
+
+The CodeHilite Extension adds code/syntax highlighting to standard 
+Python-Markdown code blocks using [Pygments][].
+
+[Python-Markdown]: http://www.freewisdom.org/projects/python-markdown/
+[Pygments]: http://pygments.org/
+
+This extension is included in the  Markdown library.
+
+Setup
+-----
+
+You will also need to [download][dl] and install the Pygments package on your 
+`PYTHONPATH`. You will need to determine the appropriate CSS classes and create
+appropriate rules for them, which are either defined in or linked from the 
+header of your HTML templates. See the excellent [documentation][] for more 
+details. If no language is defined, Pygments will attempt to guess the 
+language. When that fails, the code block will display as un-highlighted code.
+
+[dl]: http://pygments.org/download/
+[documentation]: http://pygments.org/docs
+
+**Note:** The css and/or javascript is not included as part of this extension 
+but shall always be provided by the end user.
+
+Syntax
+------
+
+The CodeHilite Extension follows the same [syntax][] as regular Markdown code 
+blocks, with one exception. The hiliter needs to know what language to use for 
+the code block. There are three ways to tell the hiliter what language the code 
+block contains and each one has a different result.
+
+[syntax]: http://daringfireball.net/projects/markdown/syntax#precode
+
+###SheBang (with path)
+
+If the first line of the codeblock contains a shebang, the language is derived 
+from that and line numbers are used.
+
+        #!/usr/bin/python
+        # Code goes here ...
+
+Will result in:
+
+    #!/usr/bin/python
+    # Code goes here ...
+
+
+###SheBang (no path)
+
+If the first line contains a shebang, but the shebang line does not contain a 
+path (a single `/` or even a space), then that line is removed from the code 
+block before processing. Line numbers are used.
+
+        #!python
+        # Code goes here ...
+
+Will result in:
+
+    # Code goes here ...
+
+####Colons
+
+If the first line begins with three or more colons, the text following the 
+colons identifies the language. The first line is removed from the code block 
+before processing and line numbers are not used.
+
+        :::python
+        # Code goes here ...
+
+Will result in:
+
+    # Code goes here ...
+
+###When No Language is Defined
+
+CodeHilite is completely backward compatible so that if a code block is 
+encountered that does not define a language, the block is simple wrapped in 
+`<pre>` tags and output. Note: one exception would be that the Pygments 
+highlighting engine will try to guess the language. Upon failure, the same 
+behavior will happen as described here.
+
+        # Code goes here ...
+
+Will result in:
+
+    # Code goes here ...
+
+Lets see the source for that:
+
+    <div class="codehilite" ><pre><code># Code goes here ...
+    </code></pre></div>
+
+Usage
+-----
+
+From the Python interpreter:
+
+    >>> html = markdown.markdown(text, ['codehilite'])
+
+If you want every code block to have line numbers, even when using colons 
+(`:::`) for language identification, the setting `force_linenos` is available 
+to do so.
+
+    >>> html = markdown.markdown(text, 
+    ...     ['codehilite(force_linenos=True)']
+    ... )
+
+If you want to prevent Pygments from guessing the language, only highlighting
+blocks when you explicitly request it, set the `guess_lang` setting to 'False'.
+
+    >>> html = markdown.markdown(text,
+    ...     ['codehilite(guess_lang=False)']
+    ... )
-- 
cgit v1.2.3