aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2009-03-16 22:26:36 -0400
committerWaylan Limberg <waylan@gmail.com>2009-03-16 22:26:36 -0400
commit38100c98962e14d1db31b279d4d7b267a96faf0b (patch)
treec0fed632555d04063b42caf3b0beb60d34391a61
parentcdcfbacb23a5b9bc5a1c1af058d90e61364d61b0 (diff)
downloadmarkdown-38100c98962e14d1db31b279d4d7b267a96faf0b.tar.gz
markdown-38100c98962e14d1db31b279d4d7b267a96faf0b.tar.bz2
markdown-38100c98962e14d1db31b279d4d7b267a96faf0b.zip
Added docs regarding output formats and a few other changes/cleanup to the docs.
-rw-r--r--docs/command_line.txt6
-rw-r--r--docs/using_as_module.txt48
-rw-r--r--docs/writing_extensions.txt2
3 files changed, 43 insertions, 13 deletions
diff --git a/docs/command_line.txt b/docs/command_line.txt
index 1ea7302..a357a54 100644
--- a/docs/command_line.txt
+++ b/docs/command_line.txt
@@ -10,8 +10,8 @@ Setup
-----
Generally, you may simply call the ``python markdown.py`` file from the command
-line. However, if you have fully installed Markdown (``setup.py install`` of
-``easyinstall``), then the ``markdown.py`` script will have been copied to
+line. However, if you have fully installed Markdown (``setup.py install`` or
+``easy_install``), then the ``markdown.py`` script will have been copied to
you Python "Scripts" directory. Different systems require different methods to
ensure that any files in the Python "Scripts" directory are on your system
path.
@@ -37,7 +37,7 @@ path.
* **Linux**:
As each Linux distribution is different and we can't possible document all
- of them here, We'll provide a few helpful pointers:
+ of them here, we'll provide a few helpful pointers:
* 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.
diff --git a/docs/using_as_module.txt b/docs/using_as_module.txt
index 11bad24..da6b1fd 100644
--- a/docs/using_as_module.txt
+++ b/docs/using_as_module.txt
@@ -15,8 +15,8 @@ To use markdown as a module:
Encoded Text
------------
-Note that ``markdown()`` expects either a simple ASCII string or **Unicode**
-as input and returns output as Unicode. Do not pass encoded strings to it!
+Note that ``markdown()`` expects **Unicode** as input (although a simple ASCII
+string should work) and returns output as Unicode. Do not pass encoded strings to it!
If your input is encoded, e.g. as UTF-8, it is your responsibility to decode
it. E.g.:
@@ -24,7 +24,7 @@ it. E.g.:
text = input_file.read()
html = markdown.markdown(text, extensions)
-If you later want to write it to disk, you should encode it:
+If you later want to write it to disk, you should encode it yourself:
output_file = codecs.open("some_file.html", "w", encoding="utf8")
output_file.write(html)
@@ -36,10 +36,12 @@ If you want to pass more options, you can create an instance of the ``Markdown``
class yourself and then use ``convert()`` to generate HTML:
import markdown
- md = markdown.Markdown(extensions=['footnotes'],
- extension_configs= {'footnotes' :
- ('PLACE_MARKER','~~~~~~~~')}
- encoding='utf8',
+ md = markdown.Markdown(
+ extensions=['footnotes'],
+ extension_configs= {'footnotes' : ('PLACE_MARKER','~~~~~~~~')},
+ safe_mode=True,
+ output_format='html4'
+ )
return md.convert(some_text)
You should also use this method if you want to process multiple strings:
@@ -56,7 +58,7 @@ encoding/decoding is required for the command line features. These functions
and methods are only intended to fit the common use case.
The ``Markdown`` class has the method ``convertFile`` which reads in a file and
-writes out to file-like-object:
+writes out to a file-like-object:
md = markdown.Markdown()
md.convertFile(input="in.txt", output="out.html", encoding="uft8")
@@ -80,10 +82,10 @@ Using Extensions
----------------
One of the parameters that you can pass is a list of Extensions. Extensions
-must be available as python modules either within the ``markdown_extensions``
+must be available as python modules either within the ``markdown.extensions``
package or on your PYTHONPATH with names starting with `mdx_`, followed by the
name of the extension. Thus, ``extensions=['footnotes']`` will first look for
-the module ``markdown_extensions.footnotes``, then a module named
+the module ``markdown.extensions.footnotes``, then a module named
``mdx_footnotes``. See the documentation specific to the extension you are
using for help in specifying configuration settings for that extension.
@@ -120,3 +122,29 @@ still create links using Markdown syntax.)
* To escape HTML, set ``safe_mode="escape"``. The HTML will be escaped and
included in the document.
+Output Formats
+--------------
+
+If Markdown is outputing (X)HTML as part of a web page, most likely you will
+want the output to match the (X)HTML version used by the rest of your page/site.
+Currenlty, Markdown offers two output formats out of the box; "HTML4" and
+"XHTML1" (the default) . Markdown will also accept the formats "HTML" and
+"XHTML" which currently map to "HTML4" and "XHTML" respectively. However,
+you should use the more explicit keys as the general keys may change in the
+future if it makes sense at that time. The keys can either be lowercase or
+uppercase.
+
+To set the output format do:
+
+ html = markdown.markdown(text, output_format='html4')
+
+Or, when using the Markdown class:
+
+ md = markdown.Markdown(output_format='html4')
+ html = md.convert(text)
+
+Note that the output format is only set once for the class and cannot be
+specified each time ``convert()`` is called. If you really must change the
+output format for the class, you can use the ``set_output_format`` method:
+
+ md.set_output_format('xhtml1')
diff --git a/docs/writing_extensions.txt b/docs/writing_extensions.txt
index 29d80e0..77c6bde 100644
--- a/docs/writing_extensions.txt
+++ b/docs/writing_extensions.txt
@@ -385,6 +385,8 @@ arguments:
Some other things you may want to access in the markdown instance are:
* ``md.htmlStash``
+ * ``md.output_formats``
+ * ``md.set_output_format()``
* ``md.registerExtension()``
* **``md_globals``**: