1PHP SmartyPants 2=============== 3 4Version 1.5.1e - Fri 9 Dec 2005 5 6by Michel Fortin 7<http://www.michelf.com/> 8 9based on work by John Gruber 10<http://daringfireball.net/> 11 12 13Introduction 14------------ 15 16PHP SmartyPants is a port to PHP of the original SmartyPants written 17in Perl by John Gruber. 18 19PHP SmartyPants is a free web publishing plug-in for WordPress and 20Smarty template engine that easily translates plain ASCII punctuation 21characters into "smart" typographic punctuation HTML entities. 22SmartyPants can also be invoked as a standalone PHP function. 23 24SmartyPants can perform the following transformations: 25 26* Straight quotes (`"` and `'`) into "curly" quote HTML entities 27* Backtick-style quotes (` ``like this'' `) into "curly" quote HTML 28 entities 29* Dashes (`--` and `---`) into en- and em-dash entities 30* Three consecutive dots (`...`) into an ellipsis entity 31 32This means you can write, edit, and save using plain old ASCII straight 33quotes, plain dashes, and plain dots, but your published posts (and 34final HTML output) will appear with smart quotes, em-dashes, and proper 35ellipses. 36 37SmartyPants does not modify characters within `<pre>`, `<code>`, 38`<kbd>`, or `<script>` tag blocks. Typically, these tags are used to 39display text where smart quotes and other "smart punctuation" would not 40be appropriate, such as source code or example markup. 41 42 43### Backslash Escapes ### 44 45If you need to use literal straight quotes (or plain hyphens and 46periods), SmartyPants accepts the following backslash escape sequences 47to force non-smart punctuation. It does so by transforming the escape 48sequence into a decimal-encoded HTML entity: 49 50 51 Escape Value Character 52 ------ ----- --------- 53 \\ \ \ 54 \" " " 55 \' ' ' 56 \. . . 57 \- - - 58 \` ` ` 59 60 61This is useful, for example, when you want to use straight quotes as 62foot and inch marks: 63 64 6\'2\" tall 65 66translates into: 67 68 6'2" tall 69 70in SmartyPants's HTML output. Which, when rendered by a web browser, 71looks like: 72 73 6'2" tall 74 75 76Installation and Requirement 77---------------------------- 78 79PHP SmartyPants require PHP version 4.0.5 or later. 80 81 82### WordPress ### 83 84WordPress already include a filter called "Texturize" with the same 85goal as SmartyPants. You could still find some usefulness to 86PHP SmartyPants if you are not happy enough with the standard algorithm. 87 88PHP SmartyPants works with [WordPress][wp], version 1.2 or later. 89 90[wp]: http://wordpress.org/ 91 921. To use PHP SmartyPants with WordPress, place the "smartypants.php" 93 file in the "plugins" folder. This folder is hidden inside 94 "wp-content" at the root of your site: 95 96 (site home)/wp-content/plugins/smartypants.php 97 982. Activate the plugin with the administrative interface of WordPress. 99 In the "Plugins" section you will now find SmartyPants. To activate 100 the plugin, click on the "Activate" button on the same line than 101 SmartyPants. Your entries will now be filtered by PHP SmartyPants. 102 103Note: It is not possible at this time to apply a different set of 104filters to different entries. All your entries will be filtered by 105PHP SmartyPants if the plugin is active. This is currently a limitation 106of WordPress. 107 108 109### Blosxom ### 110 111SmartyPants works with Blosxom version 2.0 or later. 112 1131. Rename the "SmartyPants.pl" plug-in to "SmartyPants" (case is 114 important). Movable Type requires plug-ins to have a ".pl" 115 extension; Blosxom forbids it (at least as of this writing). 116 1172. Copy the "SmartyPants" plug-in file to your Blosxom plug-ins folder. 118 If you're not sure where your Blosxom plug-ins folder is, see the 119 Blosxom documentation for information. 120 1213. That's it. The entries in your weblog should now automatically have 122 SmartyPants's default transformations applied. 123 1244. If you wish to configure SmartyPants's behavior, open the 125 "SmartyPants" plug-in, and edit the value of the `$smartypants_attr` 126 configuration variable, located near the top of the script. The 127 default value is 1; see "Options", below, for the full list of 128 supported values. 129 130 131### In your programs ### 132 133You can use PHP SmartyPants easily in your current PHP program. Simply 134include the file and then call the `SmartyPants` function on the text 135you want to convert: 136 137 include_once "smartypants.php"; 138 $my_text = SmartyPants($my_text); 139 140 141### With Smarty ### 142 143If your program use the [Smarty][sm] template engine, PHP SmartyPants 144can now be used as a modifier for your templates. Rename 145"smartypants.php" to "modifier.smartypants.php" and put it in your 146smarty plugins folder. 147 148[sm]: http://smarty.php.net/ 149 150 151Options and Configuration 152------------------------- 153 154Settings are specified by editing the value of the `$smartypants_attr` 155variable in the "smartypants.php" file. For users of the Smarty template 156engine, the "smartypants" modifier also takes an optional attribute where 157you can specify configuration options, like this: 158`{$var|smartypants:1}` (where "1" is the configuration option). 159 160Numeric values are the easiest way to configure SmartyPants's behavior: 161 162"0" 163 Suppress all transformations. (Do nothing.) 164 165"1" 166 Performs default SmartyPants transformations: quotes (including 167 backticks-style), em-dashes, and ellipses. `--` (dash dash) is 168 used to signify an em-dash; there is no support for en-dashes. 169 170"2" 171 Same as smarty_pants="1", except that it uses the old-school 172 typewriter shorthand for dashes: `--` (dash dash) for en-dashes, 173 `---` (dash dash dash) for em-dashes. 174 175"3" 176 Same as smarty_pants="2", but inverts the shorthand for dashes: `--` 177 (dash dash) for em-dashes, and `---` (dash dash dash) for en-dashes. 178 179"-1" 180 Stupefy mode. Reverses the SmartyPants transformation process, 181 turning the HTML entities produced by SmartyPants into their ASCII 182 equivalents. E.g. `“` is turned into a simple double-quote 183 (`"`), `—` is turned into two dashes, etc. This is useful if you 184 wish to suppress smart punctuation in specific pages, such as 185 RSS feeds. 186 187The following single-character attribute values can be combined to 188toggle individual transformations from within the smarty_pants 189attribute. For example, to educate normal quotes and em-dashes, but not 190ellipses or backticks-style quotes: 191 192 $smartypants_attr = "qd"; 193 194Or inside a Smarty template: 195 196 {$var|smartypants:"qd"} 197 198"q" 199 Educates normal quote characters: (`"`) and (`'`). 200 201"b" 202 Educates ` ``backticks'' ` double quotes. 203 204"B" 205 Educates backticks-style double quotes and ` `single' ` quotes. 206 207"d" 208 Educates em-dashes. 209 210"D" 211 Educates em-dashes and en-dashes, using old-school typewriter 212 shorthand: (dash dash) for en-dashes, (dash dash dash) for 213 em-dashes. 214 215"i" 216 Educates em-dashes and en-dashes, using inverted old-school 217 typewriter shorthand: (dash dash) for em-dashes, (dash dash dash) 218 for en-dashes. 219 220"e" 221 Educates ellipses. 222 223"w" 224 Translates any instance of `"` into a normal double-quote 225 character. This should be of no interest to most people, but of 226 particular interest to anyone who writes their posts using 227 Dreamweaver, as Dreamweaver inexplicably uses this entity to 228 represent a literal double-quote character. SmartyPants only 229 educates normal quotes, not entities (because ordinarily, entities 230 are used for the explicit purpose of representing the specific 231 character they represent). The "w" option must be used in 232 conjunction with one (or both) of the other quote options ("q" or 233 "b"). Thus, if you wish to apply all SmartyPants transformations 234 (quotes, en- and em-dashes, and ellipses) and also translate 235 `"` entities into regular quotes so SmartyPants can educate 236 them, you should pass the following to the smarty_pants attribute: 237 238 $smartypants_attr = "qDew"; 239 240 Inside a Smarty template, this will be: 241 242 {$var|smartypants:"qDew"} 243 244 245Caveats 246------- 247 248### Why You Might Not Want to Use Smart Quotes in Your Weblog ### 249 250For one thing, you might not care. 251 252Most normal, mentally stable individuals do not take notice of proper 253typographic punctuation. Many design and typography nerds, however, 254break out in a nasty rash when they encounter, say, a restaurant sign 255that uses a straight apostrophe to spell "Joe's". 256 257If you're the sort of person who just doesn't care, you might well want 258to continue not caring. Using straight quotes -- and sticking to the 2597-bit ASCII character set in general -- is certainly a simpler way to 260live. 261 262Even if you *do* care about accurate typography, you still might want to 263think twice before educating the quote characters in your weblog. One 264side effect of publishing curly quote HTML entities is that it makes 265your weblog a bit harder for others to quote from using copy-and-paste. 266What happens is that when someone copies text from your blog, the copied 267text contains the 8-bit curly quote characters (as well as the 8-bit 268characters for em-dashes and ellipses, if you use these options). These 269characters are not standard across different text encoding methods, 270which is why they need to be encoded as HTML entities. 271 272People copying text from your weblog, however, may not notice that 273you're using curly quotes, and they'll go ahead and paste the unencoded 2748-bit characters copied from their browser into an email message or 275their own weblog. When pasted as raw "smart quotes", these characters 276are likely to get mangled beyond recognition. 277 278That said, my own opinion is that any decent text editor or email client 279makes it easy to stupefy smart quote characters into their 7-bit 280equivalents, and I don't consider it my problem if you're using an 281indecent text editor or email client. 282 283### Algorithmic Shortcomings ### 284 285One situation in which quotes will get curled the wrong way is when 286apostrophes are used at the start of leading contractions. For example: 287 288 'Twas the night before Christmas. 289 290In the case above, SmartyPants will turn the apostrophe into an opening 291single-quote, when in fact it should be a closing one. I don't think 292this problem can be solved in the general case -- every word processor 293I've tried gets this wrong as well. In such cases, it's best to use the 294proper HTML entity for closing single-quotes (`’` or `’`) by 295hand. 296 297 298Bugs 299---- 300 301To file bug reports or feature requests (other than topics listed in the 302Caveats section above) please send email to: 303 304<michel.fortin@michelf.com> 305 306If the bug involves quotes being curled the wrong way, please send 307example text to illustrate. 308 309 310Version History 311--------------- 312 3131.5.1e (9 Dec 2005) 314 315* Corrected a bug that prevented special characters from being 316 escaped. 317 318 3191.5.1d (6 Jun 2005) 320 321* Correct a small bug in `_TokenizeHTML` where a Doctype declaration 322 was not seen as HTML, making curly quotes inside it. 323 324 3251.5.1c (13 Dec 2004) 326 327* Changed a regular expression in `_TokenizeHTML` that could lead 328 to a segmentation fault with PHP 4.3.8 on Linux. 329 330 3311.5.1b (6 Sep 2004) 332 333* Corrected a problem with quotes immediately following a dash 334 with no space between: `Text--"quoted text"--text.` 335 336* PHP SmartyPants can now be used as a modifier by the Smarty 337 template engine. Rename the file to "modifier.smartypants.php" 338 and put it in your smarty plugins folder. 339 340* Replaced a lot of spaces characters by tabs, saving about 4 KB. 341 342 3431.5.1a (30 Jun 2004) 344 345* PHP Markdown and PHP Smartypants now share the same `_TokenizeHTML` 346 function when loaded simultanously. 347 348* Changed the internals of `_TokenizeHTML` to lower the PHP version 349 requirement to PHP 4.0.5. 350 351 3521.5.1 (6 Jun 2004) 353 354* Initial release of PHP SmartyPants, based on version 1.5.1 of the 355 original SmartyPants written in Perl. 356 357 358Copyright and License 359--------------------- 360 361Copyright (c) 2005 Michel Fortin 362<http://www.michelf.com/> 363All rights reserved. 364 365Copyright (c) 2003-2004 John Gruber 366<http://daringfireball.net/> 367All rights reserved. 368 369Redistribution and use in source and binary forms, with or without 370modification, are permitted provided that the following conditions are 371met: 372 373* Redistributions of source code must retain the above copyright notice, 374 this list of conditions and the following disclaimer. 375 376* Redistributions in binary form must reproduce the above copyright 377 notice, this list of conditions and the following disclaimer in the 378 documentation and/or other materials provided with the distribution. 379 380* Neither the name "SmartyPants" nor the names of its contributors may 381 be used to endorse or promote products derived from this software 382 without specific prior written permission. 383 384This software is provided by the copyright holders and contributors "as 385is" and any express or implied warranties, including, but not limited 386to, the implied warranties of merchantability and fitness for a 387particular purpose are disclaimed. In no event shall the copyright owner 388or contributors be liable for any direct, indirect, incidental, special, 389exemplary, or consequential damages (including, but not limited to, 390procurement of substitute goods or services; loss of use, data, or 391profits; or business interruption) however caused and on any theory of 392liability, whether in contract, strict liability, or tort (including 393negligence or otherwise) arising in any way out of the use of this 394software, even if advised of the possibility of such damage. 395