aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2013-02-27 12:52:02 -0500
committerWaylan Limberg <waylan@gmail.com>2013-02-27 12:52:02 -0500
commit26ebafb3b86b224c2acad29bf4d4314a3242189a (patch)
treeeb3ae02a639e724b794319f8884698b14385f3a9 /docs
parent52613ceeed7b022a799be7b52775c8705133eca7 (diff)
downloadmarkdown-26ebafb3b86b224c2acad29bf4d4314a3242189a.tar.gz
markdown-26ebafb3b86b224c2acad29bf4d4314a3242189a.tar.bz2
markdown-26ebafb3b86b224c2acad29bf4d4314a3242189a.zip
Tweaked the docs some more.
Diffstat (limited to 'docs')
-rw-r--r--docs/cli.txt37
-rw-r--r--docs/extensions/api.txt2
-rw-r--r--docs/extensions/code_hilite.txt70
-rw-r--r--docs/extensions/index.txt2
-rw-r--r--docs/index.txt1
-rw-r--r--docs/release-2.3.txt16
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