docutils/docs/user/smartquotes.txt

   1 =========================
   2 Smart Quotes for Docutils
   3 =========================
   4
   5 :Author: Günter Milde,
   6          based on SmartyPants by John Gruber, Brad Choate, and Chad Miller
   7 :Contact: docutils-develop@lists.sourceforge.net
   8 :Revision: $Revision$
   9 :Date: $Date$
  10 :License: Released under the terms of the `2-Clause BSD license`_
  11 :Abstract: This document describes the Docutils `smartquotes` module.
  12
  13 .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
  14
  15 .. contents::
  16
  17 Description
  18 ===========
  19
  20 The `smart_quotes configuration setting`_ triggers the SmartQuotes
  21 transformation on Text nodes that includes the following steps:
  22
  23 - Straight quotes (``"`` and ``'``) into "curly" quote characters
  24 - dashes (``--`` and ``---``) into en- and em-dash entities
  25 - three consecutive dots (``...`` or ``. . .``) into an ellipsis entity.
  26
  27 This means you can write, edit, and save your documents using plain old
  28 ASCII---straight quotes, plain dashes, and plain dots---while Docutils
  29 generates documents with typographical quotes, dashes, and ellipses.
  30
  31 Advantages:
  32
  33 * typing speed (especiall when blind-typing),
  34 * the possibility to change the quoting style of the
  35   complete document with just one configuration option, and
  36 * restriction to 7-bit characters in the source.
  37
  38 However, there are `algorithmic shortcomings`_ for 2 reasons:
  39
  40 * Dual use of the "ASCII-apostrophe" (') as single quote and apostrophe,
  41 * languages that do not use whitespace around words.
  42
  43 So, please consider also
  44 `Why You Might Not Want to Use "Smart" Quotes in Your Documents`_.
  45
  46 .. _smart_quotes configuration setting: config.html#smart-quotes
  47
  48
  49 Escaping
  50 ========
  51
  52 The `SmartQuotes` transform does not modify characters in literal text
  53 such as source code, maths, or literal blocks.
  54
  55 If you need literal straight quotes (or plain hyphens and periods) in normal
  56 text, you can backslash escape the characters to preserve
  57 ASCII-punctuation. You need two backslashes as one backslash is removed by
  58 the reStructuredText `escaping mechanism`_.
  59
  60 ========  =========  ========  =========
  61 Escape    Character  Escape    Character
  62 ========  =========  ========  =========
  63 ``\\``    \\         ``\\.``   \\.
  64 ``\\"``   \\"        ``\\-``   \\-
  65 ``\\'``   \\'        ``\\```   \\`
  66 ========  =========  ========  =========
  67
  68 This is useful, for example, when you want to use straight quotes as
  69 foot and inch marks: 6\\'2\\" tall; a 17\\" iMac.
  70
  71 .. _escaping mechanism: ../ref/rst/restructuredtext.html#escaping-mechanism
  72
  73
  74 Localisation
  75 ============
  76
  77 Quotation marks have a `variety of forms`__ in different languages and
  78 media.
  79
  80 `Smartquotes` selects quotation marks depending on the language of the current
  81 block element and the value of the `smart_quotes configuration setting`_.
  82
  83 __ https://en.wikipedia.org/wiki/Quotation_mark#Summary_table
  84
  85 Docutils' `smartquotes` support the following languages:
  86
  87
  88 .. class:: language-af
  89
  90 "'Afrikaans' quotes"
  91
  92 .. class:: language-af-x-altquot
  93
  94 "'Afrikaans' alternative quotes"
  95
  96 .. class:: language-ca
  97
  98 "'Catalan' quotes"
  99
 100 .. class:: language-ca-x-altquot
 101
 102 "'Catalan' alternative quotes"
 103
 104 .. class:: language-cs
 105
 106 "'Czech' quotes"
 107
 108 .. class:: language-cs-x-altquot
 109
 110 "'Czech' alternative quotes"
 111
 112 .. class:: language-da
 113
 114 "'Danish' quotes"
 115
 116 .. class:: language-da-x-altquot
 117
 118 "'Danish' alternative quotes"
 119
 120 .. class:: language-de
 121
 122 "'German' quotes"
 123
 124 .. class:: language-de-x-altquot
 125
 126 "'German' alternative quotes"
 127
 128 .. class:: language-de-ch
 129
 130 "'Swiss-German' quotes"
 131
 132 .. class:: language-el
 133
 134 "'Greek' quotes"
 135
 136 .. class:: language-en
 137
 138 "'English' quotes"
 139
 140 .. class:: language-en-uk-x-altquot
 141
 142 "'British' alternative quotes"
 143 (swaps single and double quotes: ``"`` → ‘ and ``'`` → “)
 144
 145 .. class:: language-eo
 146
 147 "'Esperanto' quotes"
 148
 149 .. class:: language-es
 150
 151 "'Spanish' quotes"
 152
 153 .. class:: language-es-x-altquot
 154
 155 "'Spanish' alternative quotes"
 156
 157 .. class:: language-et
 158
 159 "'Estonian' quotes" (no secondary quote listed in Wikipedia)
 160
 161 .. class:: language-et-x-altquot
 162
 163 "'Estonian' alternative quotes"
 164
 165 .. class:: language-eu
 166
 167 "'Basque' quotes"
 168
 169 .. class:: language-fi
 170
 171 "'Finnish' quotes"
 172
 173 .. class:: language-fi-x-altquot
 174
 175 "'Finnish' alternative quotes"
 176
 177 .. class:: language-fr
 178
 179 "'French' quotes"
 180
 181 .. class:: language-fr-x-altquot
 182
 183 "'French' alternative quotes"
 184
 185 .. class:: language-fr-ch
 186
 187 "'Swiss-French' quotes"
 188
 189 .. class:: language-fr-ch-x-altquot
 190
 191 "'Swiss-French' alternative quotes" (narrow no-break space, see
 192 http://typoguide.ch/)
 193
 194 .. class:: language-gl
 195
 196 "'Galician' quotes"
 197
 198 .. class:: language-he
 199
 200 "'Hebrew' quotes"
 201
 202 .. class:: language-he-x-altquot
 203
 204 "'Hebrew' alternative quotes"
 205
 206 .. class:: language-hr
 207
 208 "'Croatian' quotes"
 209
 210 .. class:: language-hr-x-altquot
 211
 212 "'Croatian' alternative quotes"
 213
 214 .. class:: language-hsb
 215
 216 "'Upper Sorbian' quotes"
 217
 218 .. class:: language-hsb-x-altquot
 219
 220 "'Upper Sorbian' alternative quotes"
 221
 222 .. class:: language-hu
 223
 224 "'Hungarian' quotes"
 225
 226 .. class:: language-is
 227
 228 "'Icelandic' quotes"
 229
 230 .. class:: language-it
 231
 232 "'Italian' quotes"
 233
 234 .. class:: language-it-ch
 235
 236 "'Swiss-Italian' quotes"
 237
 238 .. class:: language-it-x-altquot
 239
 240 "'Italian' alternative quotes"
 241
 242 .. class:: language-ja
 243
 244 "'Japanese' quotes"
 245
 246 .. class:: language-lt
 247
 248 "'Lithuanian' quotes"
 249
 250 .. class:: language-lv
 251
 252 "'Latvian' quotes"
 253
 254 .. class:: language-nl
 255
 256 "'Dutch' quotes"
 257
 258 .. class:: language-nl-x-altquot
 259
 260 "'Dutch' alternative quotes"
 261
 262 .. # 'nl-x-altquot2': u'””’’',
 263
 264 .. class:: language-pl
 265
 266 "'Polish' quotes"
 267
 268 .. class:: language-pl-x-altquot
 269
 270 "'Polish' alternative quotes"
 271
 272 .. class:: language-pt
 273
 274 "'Portuguese' quotes"
 275
 276 .. class:: language-pt-br
 277
 278 "'Portuguese (Brazil)' quotes"
 279
 280 .. class:: language-ro
 281
 282 "'Romanian' quotes"
 283
 284 .. class:: language-ru
 285
 286 "'Russian' quotes"
 287
 288 .. class:: language-sh
 289
 290 "'Serbo-Croatian' quotes"
 291
 292 .. class:: language-sh-x-altquot
 293
 294 "'Serbo-Croatian' alternative quotes"
 295
 296 .. class:: language-sk
 297
 298 "'Slovak' quotes"
 299
 300 .. class:: language-sk-x-altquot
 301
 302 "'Slovak' alternative quotes"
 303
 304 .. class:: language-sl
 305
 306 "'Slovenian' quotes"
 307
 308 .. class:: language-sl-x-altquot
 309
 310 "'Slovenian' alternative quotes"
 311
 312 .. class:: language-sr
 313
 314 "'Serbian' quotes"
 315
 316 .. class:: language-sr-x-altquot
 317
 318 "'Serbian' alternative quotes"
 319
 320 .. class:: language-sv
 321
 322 "'Swedish' quotes"
 323
 324 .. class:: language-sv-x-altquot
 325
 326 "'Swedish' alternative quotes"
 327
 328 .. class:: language-tr
 329
 330 "'Turkish' quotes"
 331
 332 .. class:: language-tr-x-altquot
 333
 334 "'Turkish' alternative quotes"
 335
 336 .. 'tr-x-altquot2': u'“„‘‚', # antiquated?
 337
 338 .. class:: language-uk
 339
 340 "'Ukrainian' quotes"
 341
 342 .. class:: language-uk-x-altquot
 343
 344 "'Ukrainian' alternative quotes"
 345
 346 .. class:: language-zh-cn
 347
 348 "'Chinese (China)' quotes"
 349
 350 .. class:: language-zh-tw
 351
 352 "'Chinese (Taiwan)' quotes"
 353
 354 Quotes in text blocks in a non-supported language use the document
 355 language:
 356
 357 .. class:: langugage-undefined-example
 358
 359 "'Undefined' quotes"
 360
 361
 362 Caveats
 363 =======
 364
 365 Why You Might Not Want to Use "Smart" Quotes in Your Documents
 366 --------------------------------------------------------------
 367
 368 For one thing, you might not care.
 369
 370 Most normal, mentally stable individuals do not take notice of proper
 371 typographic punctuation. Many design and typography nerds, however, break
 372 out in a nasty rash when they encounter, say, a restaurant sign that uses
 373 a straight apostrophe to spell "Joe's".
 374
 375 If you're the sort of person who just doesn't care, you might well want to
 376 continue not caring. Using straight quotes -- and sticking to the 7-bit
 377 ASCII character set in general -- is certainly a simpler way to live.
 378
 379 Even if you *do* care about accurate typography, you still might want to
 380 think twice before "auto-educating" the quote characters in your documents.
 381 As there is always a chance that the algorithm gets it wrong, you may
 382 instead prefer to use the compose key or some other means to insert the
 383 correct Unicode characters into the source.
 384
 385
 386 Algorithmic Shortcomings
 387 ------------------------
 388
 389 The ASCII character (u0027 APOSTROPHE) is used for apostrophe and single
 390 quotes. If use inside a word, it is converted into an apostrophe:
 391
 392    .. class:: language-fr
 393
 394    Il dit : "C'est 'super' !"
 395
 396 At the beginning or end of a word, it cannot be distinguished from a single
 397 quote by the algorithm.
 398
 399 The `right single quotation mark`_ character -- used to close a secondary
 400 (inner) quote in English -- is also "the preferred character to use for
 401 apostrophe" (Unicode_). Therefore, "educating" works as expected for
 402 apostrophes at the end of a word, e.g.,
 403
 404   Mr. Hastings' pen; three days' leave; my two cents' worth.
 405
 406 However, when apostrophes are used at the start of leading contractions,
 407 "educating" will turn the apostrophe into an *opening* secondary quote. In
 408 English, this is *not* the apostrophe character, e.g., ``'Twas brillig``
 409 is "miseducated" to
 410
 411   'Twas brillig.
 412
 413 In other locales (French, Italian, German, ...), secondary closing quotes
 414 differ from the apostrophe. A text like::
 415
 416    .. class:: language-de-CH
 417
 418    "Er sagt: 'Ich fass' es nicht.'"
 419
 420 becomes
 421
 422    .. class:: language-de-CH
 423
 424    "Er sagt: 'Ich fass' es nicht.'"
 425
 426 with a single closing guillemet in place of the apostrophe.
 427
 428 In such cases, it's best to use the recommended apostrophe character (’) in
 429 the source:
 430
 431    | ’Twas brillig, and the slithy toves
 432    | Did gyre and gimble in the wabe;
 433    | All mimsy were the borogoves,
 434    | And the mome raths outgrabe.
 435
 436 .. _right single quotation mark:
 437     http://www.fileformat.info/info/unicode/char/2019/index.htm
 438 .. _Unicode: http://www.unicode.org/charts/PDF/U2000.pdf
 439
 440 History
 441 =======
 442
 443 The smartquotes module is an adaption of "SmartyPants_" to Docutils.
 444
 445 `John Gruber`_ did all of the hard work of writing this software in Perl for
 446 `Movable Type`_ and almost all of this useful documentation.  `Chad Miller`_
 447 ported it to Python to use with Pyblosxom_.
 448
 449 Portions of the SmartyPants original work are based on Brad Choate's nifty
 450 MTRegex plug-in.  `Brad Choate`_ also contributed a few bits of source code to
 451 this plug-in.  Brad Choate is a fine hacker indeed.
 452 `Jeremy Hedley`_ and `Charles Wiltgen`_ deserve mention for exemplary beta
 453 testing of the original SmartyPants.
 454
 455 Internationalization and adaption to Docutils by Günter Milde.
 456
 457 .. _SmartyPants: http://daringfireball.net/projects/smartypants/
 458 .. _Pyblosxom: http://pyblosxom.bluesock.org/
 459 .. _Movable Type: http://www.movabletype.org/
 460 .. _John Gruber: http://daringfireball.net/
 461 .. _Chad Miller: http://web.chad.org/
 462 .. _Brad Choate: http://bradchoate.com/
 463 .. _Jeremy Hedley: http://antipixel.com/
 464 .. _Charles Wiltgen: http://playbacktime.com/
 465 .. _Rael Dornfest: http://raelity.org/