mdx_smartypants / README.rst

Jonathan Eunice 6ac259c 
























































Jonathan Eunice 1ad855e 

Jonathan Eunice 6ac259c 
Jonathan Eunice 1ad855e 
Jonathan Eunice 6ac259c 













Markdown is great, but if you want pretty "curled" quotes, real em- and en-dashes,
and the other typographic prettification that our modern Unicode- and Web-savvy
world affords, it needs to be married with ``smartypants`` (or an equivalent
module) to turn ugly, programmer-ish punctuation into pretty typographic punctuation.
This module does that.

Usage
=====

::
  
    import markdown
    
    text = """
    Markdown makes HTML from simple text files. But--it lacks typographic
    "prettification." That... That'd be sweet. Definitely 7---8 on a '10-point
    scale'. Now it has it.
    
    Huzzah!
    """
    
    print markdown.markdown(text, extensions=['smartypants'])

This produces nice HTML output, including typographically "pretty" quotes and
other punctuation. It also renders HTML entites in their named rather than
numeric form, which is easier on the eyes and more readily comprehended::

    <p>Markdown makes HTML from simple text files. But&mdash;it lacks
    typographic &ldquo;prettification.&rdquo; That&hellip; That&rsquo;d be
    sweet. Definitely 7&ndash;8 on a &lsquo;10-point scale&rsquo;. Now it has
    it.</p>
    <p>Huzzah!</p>
    
Note that you don't really need to do an ``import mdx_smartypants``.
You're welcome to if you like, and it may help to advertise that the code
depends on ``mdx_smartypants`` being available. But ``markdown`` will
look for ``mdx_smartypants`` simply
by virtue of the ``extensions=['smartypants']`` declaration.

``mdx_smartypants`` will not massage indented code blocks, so your
program snippets are safe.

Notes
=====

 *  The ``smartypants`` module (as of version 1.6.0.3) wrongly
    munges punctuation within style sections found in the document
    body. ``mdx_smartypants`` monkey-patches a fix for this.
    
 *  As of verison 1.2, ``mdx_smartpants`` no longer uses the stock
    ``smartypants`` module from PyPI. It incorporates a copy of
    the module, called ``spants``, in order to tweak the code
    for Python 3 compatibility. This
    is a partial step towards a rewrite of ``smartypants`` itself
    to support Python 3 and be more in-line with modern Python idioms.
 
 * Now
   successfully packaged for, and tests against, against Python 2.5,
   2.6, 2.7, 3.2, and 3.3, as well as against PyPy 1.9 (based on 2.7.2).
   
 * Automated multi-version testing managed by
   `pytest <http://pypi.python.org/pypi/pytest>`_
   and `tox <http://pypi.python.org/pypi/tox>`_.
   
Installation
============

::

    pip install mdx_smartypants

To ``easy_install`` under a specific Python version (3.3 in this example)::

    python3.3 -m easy_install mdx_smartypants
    
(You may need to prefix these with "sudo " to authorize installation.)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.