diff options
| -rw-r--r-- | docs/cli.txt | 37 | ||||
| -rw-r--r-- | docs/extensions/api.txt | 2 | ||||
| -rw-r--r-- | docs/extensions/code_hilite.txt | 70 | ||||
| -rw-r--r-- | docs/extensions/index.txt | 2 | ||||
| -rw-r--r-- | docs/index.txt | 1 | ||||
| -rw-r--r-- | docs/release-2.3.txt | 16 |
6 files changed, 72 insertions, 56 deletions
diff --git a/docs/cli.txt b/docs/cli.txt index 719bc0c..ff19501 100644 --- a/docs/cli.txt +++ b/docs/cli.txt @@ -17,21 +17,36 @@ Generally, you will want to have the Markdown library fully installed on your system to run the command line script. See the [Installation instructions](install.html) for details. -Assuming the `python` executable is on your system path, just run the following: +Python-Markdown's command line script takes advantage of Python's `-m` flag. +Therefore, assuming the python executable is on your system path, use the +following format: - python -m markdown [options] [args] + $ python -m markdown [options] [args] -That will run the module as a script. Note that on older Python versions (2.6), -you may need to specify the appropriate module: +That will run the module as a script with the options and args provided. - python -m markdown.__main__ [options] [args] +!!! Note + Unfortunately, Python 2.6 does not fully support the `-m` flag. Therefore, you + may need to specify the module in which the command line script exists + (`markdown.__main__`): -Use the `--help` option for available options: + $ python -m markdown.__main__ [options] [args] - python -m markdown --help +At its most basic usage, one would simply pass in a file name as the only argument: -If you don't want to call the python executable directly, follow the -instructions below: + $ python -m markdown input_file.txt + +Piping input and output (on STDIN and STDOUT) is fully supported as well. +For example: + + $ echo "Some **Markdown** text." | python -m markdown > output.html + +Use the `--help` option for a list all available options and args: + + $ python -m markdown --help + +If you don't want to call the python executable directly (using the `-m` flag), +follow the instructions below to use a wrapper script: Setup ----- @@ -58,8 +73,8 @@ path. * Some systems will automatically install the script on your path. Try it and see if it works. Just run ``markdown_py`` from the command line. - * Other systems may maintain a separate "Scripts" directory which you - need to add to your path. Find it (check with your distribution) and + * Other systems may maintain a separate "Scripts" ("bin") directory which + you need to add to your path. Find it (check with your distribution) and either add it to your path or make a symbolic link to it from your path. * If you are sure ``markdown_py`` is on your path, but it still isn't being diff --git a/docs/extensions/api.txt b/docs/extensions/api.txt index ac840f9..bc06154 100644 --- a/docs/extensions/api.txt +++ b/docs/extensions/api.txt @@ -594,7 +594,7 @@ the module and call the `makeExtension` function to initiate your extension. The "name" of your extension must be a string consisting of the importable path to your module using Python's dot notation. Therefore, if you are providing a library -to your users and would like to include a custom markdown extensions with your +to your users and would like to include a custom markdown extensions within your library, that extension would be named `"mylib.mdext.myext"` where `mylib/mdext/myext.py` contains the `makeExtension` function and the `mylib` directory is on the PYTHONPATH. diff --git a/docs/extensions/code_hilite.txt b/docs/extensions/code_hilite.txt index 57f81ca..2e15e58 100644 --- a/docs/extensions/code_hilite.txt +++ b/docs/extensions/code_hilite.txt @@ -51,67 +51,67 @@ block contains and each one has a different result. [syntax]: http://daringfireball.net/projects/markdown/syntax#precode -###SheBang (with path) +* ###SheBang (with path) -If the first line of the codeblock contains a shebang, the language is derived -from that and line numbers are used. + 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 ... -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. -###SheBang (no path) + #!python + # Code goes here ... -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. + Will result in: - #!python # Code goes here ... -Will result in: +* ###Colons - # Code goes here ... + 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. -####Colons + :::python + # Code goes here ... -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. + Will result in: - :::python # Code goes here ... -Will result in: +* ###When No Language is Defined - # Code goes here ... + CodeHilite is completely backward compatible so that if a code block is + encountered that does not define a language, the block is simply wrapped in + `<pre>` tags and output. -###When No Language is Defined + # Code goes here ... -CodeHilite is completely backward compatible so that if a code block is -encountered that does not define a language, the block is simply wrapped in -`<pre>` tags and output. + Will result in: # Code goes here ... -Will result in: - - # Code goes here ... + Lets see the source for that: -Lets see the source for that: + <div class="codehilite"><pre><code># Code goes here ... + </code></pre></div> - <div class="codehilite"><pre><code># Code goes here ... - </code></pre></div> - -!!! Note - When no language is defined, the Pygments highlighting engine will try to guess - the language (unless `guess_lang` is set to `False`). Upon failure, the same - behavior will happen as described above. + !!! Note + When no language is defined, the Pygments highlighting engine will try to guess + the language (unless `guess_lang` is set to `False`). Upon failure, the same + behavior will happen as described above. Usage ----- diff --git a/docs/extensions/index.txt b/docs/extensions/index.txt index 99ca8c7..934c1d6 100644 --- a/docs/extensions/index.txt +++ b/docs/extensions/index.txt @@ -20,7 +20,7 @@ See the [Library Reference](../reference.html#extensions) for more details. From the command line, specify an extension with the `-x` option. - python -m markdown -x footnotes -x tables input.txt > output.html + $ python -m markdown -x footnotes -x tables input.txt > output.html See the [Command Line docs](../cli.html) or use the `--help` option for more details. diff --git a/docs/index.txt b/docs/index.txt index b0372d8..edf1cbd 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -26,6 +26,7 @@ The Python-Markdown project is developed with the following goals in mind: follows the [syntax rules](http://daringfireball.net/projects/markdown/syntax) and the behavior of the original (markdown.pl) implementation as reasonably as possible (see [differences](#differences) for a few exceptions). + * Provide an [Extension API](extensions/api.html) which makes it possible to change and/or extend the behavior of the parser. diff --git a/docs/release-2.3.txt b/docs/release-2.3.txt index 956a303..146ab53 100644 --- a/docs/release-2.3.txt +++ b/docs/release-2.3.txt @@ -8,7 +8,7 @@ Python-Markdown 2.3 Release Notes ================================= We are pleased to release Python-Markdown 2.3 which adds one new extension, -remove an old extension, and now runs on both Python 2 and Python 3 +removes an old extension, and now runs on both Python 2 and Python 3 without running the 2to3 conversion tool. See the list of changes below for details. @@ -19,8 +19,8 @@ Backwards-incompatible Changes * Support has been dropped for Python 2.5. No guarantees are made that the library will work in any version of Python lower than 2.6. As all supported -Python versions include the ElementTree library, Python-Markdown no longer -will try to import a third-party installation of ElementTree. +Python versions include the ElementTree library, Python-Markdown will no +longer try to import a third-party installation of ElementTree. * All classes are now "new-style" classes. In other words, all classes subclass from 'object'. While this is not likely to affect most users, @@ -28,7 +28,7 @@ extension authors may need to make a few minor adjustments to their code. * "safe_mode" has been further restricted. Markdown formated links must be of a known whitelisted scheme when in "safe_mode" or the url is discarded. -The whitelesited schemes are: 'http', 'https', 'ftp', 'ftps', 'mailto', +The whitelisted schemes are: 'http', 'https', 'ftp', 'ftps', 'mailto', and 'news'. Schemeless urls are also permitted, but are checked in other ways - as they have been for some time. @@ -39,7 +39,7 @@ you will need to update your code accordingly. No changes are necessary if you are outputing XHTML (the default) or HTML4. * The "force_linenos" config setting of the CodeHilite extension has been -marked as Pending Deprecation and a new setting "linenums" has been added to +marked as **Pending Deprecation** and a new setting "linenums" has been added to replace it. See documentation for the [CodeHilite Extension] for an explanation of the new "linenums" setting. The new setting will honor the old "force_linenos" if it is set, but it will raise a PendingDeprecationWarning @@ -63,10 +63,10 @@ subdirectory of another project. The various files within the library will still import each other properly even though 'markdown' may not be in Python's root namespace. -* Added the [Admonition Extension] which implements [rST-style][rST] -admonitions to the Markdown syntax. However, be warned that this extension +* The [Admonition Extension] has been added, which implements [rST-style][rST] +admonitions in the Markdown syntax. However, be warned that this extension is experimental and the syntax and behavior is still subject to change. Please -try it out and report bugs/improvements. +try it out and report bugs and/or improvements. [Admonition Extension]: extensions/admonition.html [rST]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions |