.. include:: ../header.txt ========================= Smart Quotes for Docutils ========================= :Author: Günter Milde, based on SmartyPants by John Gruber, Brad Choate, and Chad Miller :Contact: docutils-develop@lists.sourceforge.net :Revision: $Revision: 9051 $ :Date: $Date: 2022-04-02 23:59:06 +0200 (Sa, 02. Apr 2022) $ :License: Released under the terms of the `2-Clause BSD license`_ :Abstract: This document describes the Docutils `smartquotes` module. .. _2-Clause BSD license: http://opensource.org/licenses/BSD-2-Clause .. contents:: Description =========== The `"smart_quotes" configuration setting`_ triggers the SmartQuotes transformation on Text nodes that includes the following steps: - Straight quotes (``"`` and ``'``) into "curly" quote characters - 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 documents using plain old ASCII -- straight quotes, plain dashes, and plain dots -- while Docutils generates documents with typographical quotes, dashes, and ellipses. Advantages: * Typing speed (especially when blind-typing). * The possibility to change the quoting style of the complete document with just one configuration option. * Typographical quotes with just 7-bit ASCII characters in the source. However, there are `algorithmic shortcomings`_ for 2 reasons: * Dual use of the "ASCII-apostrophe" (') as single quote and apostrophe. * Languages that do not use whitespace around words. So, please consider also `Why You Might Not Want to Use "Smart" Quotes in Your Documents`_. .. _"smart_quotes" configuration setting: .. _"smart_quotes" setting: config.html#smart-quotes Escaping ======== The `SmartQuotes` transform does not modify characters in literal text such as source code, maths, or literal blocks. If you need literal straight quotes (or plain hyphens and periods) in normal text, you can `backslash escape`_ the characters to preserve ASCII-punctuation. .. class:: booktabs ========= ========= == ======== ========== Input Output Input Output ========= ========= == ======== ========== ``\\`` \\ ``\...`` \... ``\"`` \" ``\--`` \-- ``\'`` \' ``\``` \` ========= ========= == ======== ========== This is useful, for example, when you want to use straight quotes as foot and inch marks: 6\'2\" tall; a 17\" monitor. .. _backslash escape: ../ref/rst/restructuredtext.html#escaping-mechanism Localization ============ Quotation marks have a `variety of forms`__ in different languages and media. __ https://en.wikipedia.org/wiki/Quotation_mark#Summary_table `SmartQuotes` inserts quotation marks depending on the language of the current block element and the value of the `"smart_quotes" setting`_.\ [#x-altquot]_ There is built-in support for the following languages:\ [#smartquotes-locales]_ .. class:: run-in :af: .. class:: language-af "'Afrikaans' quotes" :af-x-altquot: .. class:: language-af-x-altquot "'Afrikaans' alternative quotes" :ca: .. class:: language-ca "'Catalan' quotes" :ca-x-altquot: .. class:: language-ca-x-altquot "'Catalan' alternative quotes" :cs: .. class:: language-cs "'Czech' quotes" :cs-x-altquot: .. class:: language-cs-x-altquot "'Czech' alternative quotes" :da: .. class:: language-da "'Danish' quotes" :da-x-altquot: .. class:: language-da-x-altquot "'Danish' alternative quotes" :de: .. class:: language-de "'German' quotes" :de-x-altquot: .. class:: language-de-x-altquot "'German' alternative quotes" :de-ch: .. class:: language-de-ch "'Swiss-German' quotes" :el: .. class:: language-el "'Greek' quotes" :en: .. class:: language-en "'English' quotes" :en-uk-x-altquot: .. class:: language-en-uk-x-altquot "'British' alternative quotes" (swaps single and double quotes) :eo: .. class:: language-eo "'Esperanto' quotes" :es: .. class:: language-es "'Spanish' quotes" :es-x-altquot: .. class:: language-es-x-altquot "'Spanish' alternative quotes" :et: .. class:: language-et "'Estonian' quotes" (no secondary quote listed in Wikipedia) :et-x-altquot: .. class:: language-et-x-altquot "'Estonian' alternative quotes" :eu: .. class:: language-eu "'Basque' quotes" :fi: .. class:: language-fi "'Finnish' quotes" :fi-x-altquot: .. class:: language-fi-x-altquot "'Finnish' alternative quotes" :fr: .. class:: language-fr "'French' quotes" :fr-x-altquot: .. class:: language-fr-x-altquot "'French' alternative quotes" :fr-ch: .. class:: language-fr-ch "'Swiss-French' quotes" :fr-ch-x-altquot: .. class:: language-fr-ch-x-altquot "'Swiss-French' alternative quotes" (narrow no-break space, see http://typoguide.ch/) :gl: .. class:: language-gl "'Galician' quotes" :he: .. class:: language-he "'Hebrew' quotes" :he-x-altquot: .. class:: language-he-x-altquot "'Hebrew' alternative quotes" :hr: .. class:: language-hr "'Croatian' quotes" :hr-x-altquot: .. class:: language-hr-x-altquot "'Croatian' alternative quotes" :hsb: .. class:: language-hsb "'Upper Sorbian' quotes" :hsb-x-altquot: .. class:: language-hsb-x-altquot "'Upper Sorbian' alternative quotes" :hu: .. class:: language-hu "'Hungarian' quotes" :is: .. class:: language-is "'Icelandic' quotes" :it: .. class:: language-it "'Italian' quotes" :it-ch: .. class:: language-it-ch "'Swiss-Italian' quotes" :it-x-altquot: .. class:: language-it-x-altquot "'Italian' alternative quotes" :ja: .. class:: language-ja "'Japanese' quotes" :lt: .. class:: language-lt "'Lithuanian' quotes" :lv: .. class:: language-lv "'Latvian' quotes" :nl: .. class:: language-nl "'Dutch' quotes" :nl-x-altquot: .. class:: language-nl-x-altquot "'Dutch' alternative quotes" .. # 'nl-x-altquot2': '””’’', :pl: .. class:: language-pl "'Polish' quotes" :pl-x-altquot: .. class:: language-pl-x-altquot "'Polish' alternative quotes" :pt: .. class:: language-pt "'Portuguese' quotes" :pt-br: .. class:: language-pt-br "'Portuguese (Brazil)' quotes" :ro: .. class:: language-ro "'Romanian' quotes" :ru: .. class:: language-ru "'Russian' quotes" :sh: .. class:: language-sh "'Serbo-Croatian' quotes" :sh-x-altquot: .. class:: language-sh-x-altquot "'Serbo-Croatian' alternative quotes" :sk: .. class:: language-sk "'Slovak' quotes" :sk-x-altquot: .. class:: language-sk-x-altquot "'Slovak' alternative quotes" :sl: .. class:: language-sl "'Slovenian' quotes" :sl-x-altquot: .. class:: language-sl-x-altquot "'Slovenian' alternative quotes" :sr: .. class:: language-sr "'Serbian' quotes" :sr-x-altquot: .. class:: language-sr-x-altquot "'Serbian' alternative quotes" :sv: .. class:: language-sv "'Swedish' quotes" :sv-x-altquot: .. class:: language-sv-x-altquot "'Swedish' alternative quotes" :tr: .. class:: language-tr "'Turkish' quotes" :tr-x-altquot: .. class:: language-tr-x-altquot "'Turkish' alternative quotes" .. 'tr-x-altquot2': '“„‘‚', # antiquated? :uk: .. class:: language-uk "'Ukrainian' quotes" :uk-x-altquot: .. class:: language-uk-x-altquot "'Ukrainian' alternative quotes" :zh-cn: .. class:: language-zh-cn "'Chinese (China)' quotes" :zh-tw: .. class:: language-zh-tw "'Chinese (Taiwan)' quotes" Quotes in text blocks in a non-configured language are kept as plain quotes: :undefined: .. class:: language-undefined-example "'Undefined' quotes" .. [#x-altquot] Tags with the non-standard extension ``-x-altquot`` define the quote set used with the `"smart_quotes" setting`_ value ``"alt"``. .. [#smartquotes-locales] The definitions for language-dependend typographical quotes can be extended or overwritten using the `"smartquotes_locales" setting`_. The following example ensures a correct leading apostrophe in ``'s Gravenhage`` (at the cost of incorrect leading single quotes) in Dutch and sets French quotes to double and single guillemets with inner spacing:: smartquote-locales: nl: „”’’ fr: « : »:‹ : › .. _"smartquotes_locales" setting: config.html#smartquotes-locales Caveats ======= Why You Might Not Want to Use "Smart" Quotes in Your Documents -------------------------------------------------------------- For one thing, you might not care. Most normal, mentally stable individuals do not take notice of proper typographic punctuation. Many design and typography nerds, however, break out in a nasty rash when they encounter, say, a restaurant sign that uses a straight apostrophe to spell "Joe's". If you're the sort of person who just doesn't care, you might well want to continue not caring. Using straight quotes -- and sticking to the 7-bit ASCII character set in general -- is certainly a simpler way to live. Even if you *do* care about accurate typography, you still might want to think twice before "auto-educating" the quote characters in your documents. As there is always a chance that the algorithm gets it wrong, you may instead prefer to use the compose key or some other means to insert the correct Unicode characters into the source. Algorithmic Shortcomings ------------------------ The ASCII character (u0027 APOSTROPHE) is used for apostrophe and single quotes. If used inside a word, it is converted into an apostrophe: .. class:: language-fr Il dit : "C'est 'super' !" At the beginning or end of a word, it cannot be distinguished from a single quote by the algorithm. The `right single quotation mark`_ character -- used to close a secondary (inner) quote in English -- is also "the preferred character to use for apostrophe" (Unicode_). Therefore, "educating" works as expected for apostrophes at the end of a word, e.g., Mr. Hastings' pen; three days' leave; my two cents' worth. However, when apostrophes are used at the start of leading contractions, "educating" will turn the apostrophe into an *opening* secondary quote. In English, this is *not* the apostrophe character, e.g., ``'Twas brillig`` is "miseducated" to 'Twas brillig. In other locales (French, Italian, German, ...), secondary closing quotes differ from the apostrophe. A text like:: .. class:: language-de-CH "Er sagt: 'Ich fass' es nicht.'" becomes «Er sagt: ‹Ich fass› es nicht.›» with a single closing guillemet in place of the apostrophe. In such cases, it's best to use the recommended apostrophe character (’) in the source: | ’Twas brillig, and the slithy toves | Did gyre and gimble in the wabe; | All mimsy were the borogoves, | And the mome raths outgrabe. .. _right single quotation mark: http://www.fileformat.info/info/unicode/char/2019/index.htm .. _Unicode: https://www.unicode.org/charts/PDF/U2000.pdf History ======= The smartquotes module is an adaption of "SmartyPants_" to Docutils. `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_. 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. Internationalization and adaption to Docutils by Günter Milde. .. _SmartyPants: http://daringfireball.net/projects/smartypants/ .. _Pyblosxom: http://pyblosxom.bluesock.org/ .. _Movable Type: http://www.movabletype.org/ .. _John Gruber: http://daringfireball.net/ .. _Chad Miller: http://web.chad.org/ .. _Brad Choate: http://bradchoate.com/ .. _Jeremy Hedley: http://antipixel.com/ .. _Charles Wiltgen: http://playbacktime.com/ .. _Rael Dornfest: http://raelity.org/