[Sommaire] [Imprimer]

   1  PHP SmartyPants Typographer
   2  ===========================
   3  
   4  Version 1.0 - Wed 28 Jun 2006
   5  
   6  by Michel Fortin
   7  <http://www.michelf.com/>
   8  
   9  Original SmartyPants by John Gruber  
  10  <http://daringfireball.net/>
  11  
  12  
  13  Introduction
  14  ------------
  15  
  16  This is a special version of PHP SmartyPants with extra features. See 
  17  <http://www.michelf.com/projects/php-smartypants/typographer/> for 
  18  details.
  19  
  20  PHP SmartyPants is a free web publishing plug-in for WordPress and 
  21  Smarty template engine that easily translates plain ASCII punctuation 
  22  characters into "smart" typographic punctuation HTML entities. 
  23  SmartyPants can also be invoked as a standalone PHP function.
  24  
  25  PHP SmartyPants is a port to PHP of the original SmartyPants written 
  26  in Perl by John Gruber.
  27  
  28  SmartyPants can perform the following transformations:
  29  
  30  *   Straight quotes (`"` and `'`) into "curly" quote HTML entities
  31  *   Backtick-style quotes (` ``like this'' `) into "curly" quote HTML
  32      entities
  33  *   Dashes (`--` and `---`) into en- and em-dash entities
  34  *   Three consecutive dots (`...`) into an ellipsis entity
  35  
  36  This means you can write, edit, and save using plain old ASCII straight 
  37  quotes, plain dashes, and plain dots, but your published posts (and 
  38  final HTML output) will appear with smart quotes, em-dashes, and proper 
  39  ellipses.
  40  
  41  SmartyPants does not modify characters within `<pre>`, `<code>`,
  42  `<kbd>`, or `<script>` tag blocks. Typically, these tags are used to
  43  display text where smart quotes and other "smart punctuation" would not
  44  be appropriate, such as source code or example markup.
  45  
  46  
  47  ### Backslash Escapes ###
  48  
  49  If you need to use literal straight quotes (or plain hyphens and
  50  periods), SmartyPants accepts the following backslash escape sequences
  51  to force non-smart punctuation. It does so by transforming the escape
  52  sequence into a decimal-encoded HTML entity:
  53  
  54  
  55      Escape  Value  Character
  56      ------  -----  ---------
  57        \\    &#92;    \
  58        \"    &#34;    "
  59        \'    &#39;    '
  60        \.    &#46;    .
  61        \-    &#45;    -
  62        \`    &#96;    `
  63  
  64  
  65  This is useful, for example, when you want to use straight quotes as
  66  foot and inch marks:
  67  
  68      6\'2\" tall
  69  
  70  translates into:
  71  
  72      6&#39;2&#34; tall
  73  
  74  in SmartyPants's HTML output. Which, when rendered by a web browser,
  75  looks like:
  76  
  77      6'2" tall
  78  
  79  
  80  Installation and Requirement
  81  ----------------------------
  82  
  83  PHP SmartyPants require PHP version 4.0.5 or later.
  84  
  85  
  86  ### WordPress ###
  87  
  88  WordPress already include a filter called "Texturize" with the same 
  89  goal as SmartyPants. You could still find some usefulness to 
  90  PHP SmartyPants if you are not happy enough with the standard algorithm.
  91  
  92  PHP SmartyPants works with [WordPress][wp], version 1.2 or later.
  93  
  94  [wp]: http://wordpress.org/
  95  
  96  1.  To use PHP SmartyPants with WordPress, place the "smartypants.php" 
  97      file in the "plugins" folder. This folder is hidden inside 
  98      "wp-content" at the root of your site:
  99  
 100          (site home)/wp-content/plugins/smartypants.php
 101  
 102  2.  Activate the plugin with the administrative interface of WordPress. 
 103      In the "Plugins" section you will now find SmartyPants. To activate 
 104      the plugin, click on the "Activate" button on the same line than 
 105      SmartyPants. Your entries will now be filtered by PHP SmartyPants.
 106  
 107  Note: It is not possible at this time to apply a different set of 
 108  filters to different entries. All your entries will be filtered by 
 109  PHP SmartyPants if the plugin is active. This is currently a limitation 
 110  of WordPress.
 111  
 112  
 113  ### In your programs ###
 114  
 115  You can use PHP SmartyPants easily in your current PHP program. Simply 
 116  include the file and then call the `SmartyPants` function on the text 
 117  you want to convert:
 118  
 119      include_once "smartypants.php";
 120      $my_text = SmartyPants($my_text);
 121  
 122  
 123  ### With Smarty ###
 124  
 125  If your program use the [Smarty][sm] template engine, PHP SmartyPants 
 126  can now be used as a modifier for your templates. Rename 
 127  "smartypants.php" to "modifier.smartypants.php" and put it in your 
 128  smarty plugins folder.
 129  
 130  [sm]: http://smarty.php.net/
 131  
 132  
 133  Options and Configuration
 134  -------------------------
 135  
 136  Settings are specified by editing the value of the `$smartypants_attr`
 137  variable in the "smartypants.php" file. For users of the Smarty template 
 138  engine, the "smartypants" modifier also takes an optional attribute where 
 139  you can specify configuration options, like this: 
 140  `{$var|smartypants:1}` (where "1" is the configuration option).
 141  
 142  Numeric values are the easiest way to configure SmartyPants's behavior:
 143  
 144  "0"
 145      Suppress all transformations. (Do nothing.)
 146  
 147  "1"
 148      Performs default SmartyPants transformations: quotes (including
 149      backticks-style), em-dashes, and ellipses. `--` (dash dash) is
 150      used to signify an em-dash; there is no support for en-dashes.
 151  
 152  "2"
 153      Same as smarty_pants="1", except that it uses the old-school
 154      typewriter shorthand for dashes: `--` (dash dash) for en-dashes,
 155      `---` (dash dash dash) for em-dashes.
 156  
 157  "3"
 158      Same as smarty_pants="2", but inverts the shorthand for dashes: `--`
 159      (dash dash) for em-dashes, and `---` (dash dash dash) for en-dashes.
 160  
 161  "-1"
 162      Stupefy mode. Reverses the SmartyPants transformation process,
 163      turning the HTML entities produced by SmartyPants into their ASCII
 164      equivalents. E.g. `&#8220;` is turned into a simple double-quote
 165      (`"`), `&#8212;` is turned into two dashes, etc. This is useful if you
 166      wish to suppress smart punctuation in specific pages, such as
 167      RSS feeds.
 168  
 169  The following single-character attribute values can be combined to
 170  toggle individual transformations from within the smarty_pants
 171  attribute. For example, to educate normal quotes and em-dashes, but not
 172  ellipses or backticks-style quotes:
 173  
 174      $smartypants_attr = "qd";
 175  
 176  Or inside a Smarty template:
 177  
 178      {$var|smartypants:"qd"}
 179  
 180  "q"
 181      Educates normal quote characters: (`"`) and (`'`).
 182  
 183  "b"
 184      Educates ` ``backticks'' ` double quotes.
 185  
 186  "B"
 187      Educates backticks-style double quotes and ` `single' ` quotes.
 188  
 189  "d"
 190      Educates em-dashes.
 191  
 192  "D"
 193      Educates em-dashes and en-dashes, using old-school typewriter
 194      shorthand: (dash dash) for en-dashes, (dash dash dash) for
 195      em-dashes.
 196  
 197  "i"
 198      Educates em-dashes and en-dashes, using inverted old-school
 199      typewriter shorthand: (dash dash) for em-dashes, (dash dash dash)
 200      for en-dashes.
 201  
 202  "e"
 203      Educates ellipses.
 204  
 205  "w"
 206      Translates any instance of `&quot;` into a normal double-quote
 207      character. This should be of no interest to most people, but of
 208      particular interest to anyone who writes their posts using
 209      Dreamweaver, as Dreamweaver inexplicably uses this entity to
 210      represent a literal double-quote character. SmartyPants only
 211      educates normal quotes, not entities (because ordinarily, entities
 212      are used for the explicit purpose of representing the specific
 213      character they represent). The "w" option must be used in
 214      conjunction with one (or both) of the other quote options ("q" or
 215      "b"). Thus, if you wish to apply all SmartyPants transformations
 216      (quotes, en- and em-dashes, and ellipses) and also translate
 217      `&quot;` entities into regular quotes so SmartyPants can educate
 218      them, you should set the SMARTYPANTS_ATTR constant at the top of 
 219      the file to:
 220  
 221          define( 'SMARTYPANTS_ATTR',    "qDew" );
 222  
 223      Inside a Smarty template, you could also pass the string as a 
 224      parameter:
 225  
 226          {$var|smartypants:"qDew"}
 227  
 228  
 229  ### Algorithmic Shortcomings ###
 230  
 231  One situation in which quotes will get curled the wrong way is when
 232  apostrophes are used at the start of leading contractions. For example:
 233  
 234      'Twas the night before Christmas.
 235  
 236  In the case above, SmartyPants will turn the apostrophe into an opening
 237  single-quote, when in fact it should be a closing one. I don't think
 238  this problem can be solved in the general case -- every word processor
 239  I've tried gets this wrong as well. In such cases, it's best to use the
 240  proper HTML entity for closing single-quotes (`&#8217;` or `&rsquo;`) by
 241  hand.
 242  
 243  
 244  Bugs
 245  ----
 246  
 247  To file bug reports or feature requests (other than topics listed in the
 248  Caveats section above) please send email to:
 249  
 250  <michel.fortin@michelf.com>
 251  
 252  If the bug involves quotes being curled the wrong way, please send
 253  example text to illustrate.
 254  
 255  
 256  Version History
 257  ---------------
 258  
 259  1.0 (28 Jun 2006)
 260  
 261  *   First public release of PHP SmartyPants Typographer.