From 26ebafb3b86b224c2acad29bf4d4314a3242189a Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 27 Feb 2013 12:52:02 -0500 Subject: Tweaked the docs some more. --- docs/cli.txt | 37 +++++++++++++++------- docs/extensions/api.txt | 2 +- docs/extensions/code_hilite.txt | 70 ++++++++++++++++++++--------------------- docs/extensions/index.txt | 2 +- docs/index.txt | 1 + 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 + `
` 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
-`
` 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:
+        
# Code goes here ...
+        

 
-    
# Code goes here ...
-    

-
-!!! 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
-- 
cgit v1.2.3