1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
|
==============
smartypants.py
==============
smartypants.py is a Python port of SmartyPants_.
.. _SmartyPants: http://daringfireball.net/projects/smartypants/
.. contents:: **Contents**
Description
===========
SmartyPants can perform the following transformations:
- Straight quotes (``"`` and ``'``) into “curly” quote HTML entities
- Backticks-style quotes (````like this''``) into “curly” quote HTML entities
- Dashes (``--`` and ``---``) into en- and em-dash entities
- Three consecutive dots (``...`` or ``. . .``) into an ellipsis entity
This means you can write, edit, and save your posts using plain old
ASCII straight quotes, plain dashes, and plain dots, but your published
posts (and final HTML output) will appear with smart quotes, em-dashes,
and proper ellipses.
SmartyPants does not modify characters within ``<pre>``, ``<code>``, ``<kbd>``,
``<math>`` or ``<script>`` tag blocks. Typically, these tags are used to
display text where smart quotes and other "smart punctuation" would not be
appropriate, such as source code or example markup.
Installation
============
smartypants.py can be installed vi pip::
$ pip install smartypants
Usage
=====
Using as module:
.. code:: python
import smartypants
text = '"SmartyPants" is smart, so is <code>smartypants.py</code> -- a Python port'
print(smartypants.smartyPants(text))
smartypants.py ships with a command-line script called ``smartypants``, it can be invoked like:
.. code:: sh
$ echo '"SmartyPants" is smart, so is <code>smartypants.py</code> -- a Python port' | smartypants
Both produce same output::
“SmartyPants” is smart, so is <code>smartypants.py</code> — a Python port
Backslash Escapes
=================
If you need to use literal straight quotes (or plain hyphens and
periods), SmartyPants accepts the following backslash escape sequences
to force non-smart punctuation. It does so by transforming the escape
sequence into a decimal-encoded HTML entity:
+--------+----------+-------------+
| Escape | Value | Character |
+========+==========+=============+
| ``\\`` | ``#92;`` | ``\`` |
+--------+----------+-------------+
| ``\"`` | ``#34;`` | ``"`` |
+--------+----------+-------------+
| ``\'`` | ``#39;`` | ``'`` |
+--------+----------+-------------+
| ``\.`` | ``#46;`` | ``.`` |
+--------+----------+-------------+
| ``\-`` | ``#45;`` | ``-`` |
+--------+----------+-------------+
| ``\``` | ``#96;`` | ``\``` |
+--------+----------+-------------+
This is useful, for example, when you want to use straight quotes as
foot and inch marks: 6'2" tall; a 17" iMac.
Options
=======
smartypants.py only accepts SmartyPants attributes, which are accessible via
``smartypants.Attr``:
``Attr.q``
Educates normal quote characters: (") and (').
``Attr.b``
Educates \`\`backticks''-style double quotes.
``Attr.B``
Educates \`\`backticks''-style double quotes and \`single' quotes.
``Attr.d``
Educates em-dashes.
``Attr.D``
Educates em-dashes and en-dashes, using old-school typewriter shorthand:
(dash dash) for en-dashes, (dash dash dash) for em-dashes.
``Attr.i``
Educates em-dashes and en-dashes, using inverted old-school typewriter
shorthand: (dash dash) for em-dashes, (dash dash dash) for en-dashes.
``Attr.e``
Educates ellipses.
``Attr.w``
Translates any instance of ``"`` into a normal double-quote character.
This should be of no interest to most people, but of particular interest
to anyone who writes their posts using Dreamweaver, as Dreamweaver
inexplicably uses this entity to represent a literal double-quote
character. SmartyPants only educates normal quotes, not entities (because
ordinarily, entities are used for the explicit purpose of representing the
specific character they represent). The "w" option must be used in
conjunction with one (or both) of the other quote options ("q" or "b").
Thus, if you wish to apply all SmartyPants transformations (quotes, en-
and em-dashes, and ellipses) and also translate ``"`` entities into
regular quotes so SmartyPants can educate them.
``Attr.s``
Stupefy mode. Reverses the SmartyPants transformation process, turning
the HTML entities produced by SmartyPants into their ASCII equivalents.
E.g. ``“`` is turned into a simple double-quote ("), ``—`` is
turned into two dashes, etc.
``Attr.set0``
Suppress all transformations. (Do nothing.)
``Attr.set1`` = ``Attr.q | Attr.b | Attr.d | Attr.e`` (Default)
Performs default SmartyPants transformations: quotes (including
\`\`backticks''-style), em-dashes, and ellipses. ``--`` (dash dash)
is used to signify an em-dash; there is no support for en-dashes.
``Attr.set2`` = ``Attr.q | Attr.b | Attr.D | Attr.e``
Same as ``Attr.set1``, except that it uses the old-school typewriter shorthand
for dashes: ``--`` (dash dash) for en-dashes, ``---`` (dash dash dash) for
em-dashes.
``Attr.set3`` = ``Attr.q | Attr.b | Attr.i | Attr.e``
Same as ``Attr.set2``, but inverts the shorthand for dashes: ``--`` (dash dash)
for em-dashes, and ``---`` (dash dash dash) for en-dashes.
``Attr.default`` = ``Attr.set1``
Will be the default argument value of ``smartyPants()`` once ``default_smartypants_attr`` removed at Version 2.0.0.
To use these attributes, simply using bitwise or:
.. code:: python
from smartypants import Attr
attrs = Attr.q | Attr.d
smartypants.smartyPants(text, attrs)
attrs = Attr.set1 | Attr.w
smartypants.smartyPants(text, attrs)
When using in command-line, use only the attribute names and drop ``set``:
.. code:: sh
attrs="qd"
echo "$text" | smartypants -a "$attrs"
attrs="1w"
echo "$text" | smartypants -a "$attrs"
Bugs
====
To file bug reports or feature requests, please `open an issue`__.
__ https://bitbucket.org/livibetter/smartypants.py/issues/new
If the bug involves quotes being curled the wrong way, please add example text
to illustrate.
History
=======
`John Gruber`_ did all of the hard work of writing this software in Perl for
`Movable Type`_ and almost all of this useful documentation. `Chad Miller`_
ported it to Python to use with Pyblosxom_.
.. _John Gruber: http://daringfireball.net/
.. _Movable Type: http://www.movabletype.org/
.. _Chad Miller: http://web.chad.org/
.. _Pyblosxom: http://pyblosxom.github.io/
Portions of the SmartyPants original work are based on Brad Choate's nifty
MTRegex plug-in. `Brad Choate`_ also contributed a few bits of source code to
this plug-in. Brad Choate is a fine hacker indeed.
`Jeremy Hedley`_ and `Charles Wiltgen`_ deserve mention for exemplary beta
testing of the original SmartyPants.
`Rael Dornfest`_ ported SmartyPants to Blosxom.
.. _Brad Choate: http://bradchoate.com/
.. _Jeremy Hedley: http://antipixel.com/
.. _Charles Wiltgen: http://playbacktime.com/
.. _Rael Dornfest: http://raelity.org/
It was later packaged for PyPI by Hao Lian.
Since August 2013, smartypants.py has been managed by `Yu-Jie Lin`_ after
contacted Chad Miller and Hao Lian. Lin took the project manager role and the
package ownership on PyPI. It has also officially supported Python 3.
.. _Yu-Jie Lin: http://yjl.im/
Copyright and License
=====================
::
Copyright (c) 2013 Yu-Jie Lin
Copyright (c) 2004, 2005, 2007, 2013 Chad Miller
Copyright (c) 2003 John Gruber
Licensed under the BSD License, for detailed license information, see COPYING
|
