source: project/wiki/eggref/4/fancypants @ 15557

Last change on this file since 15557 was 15557, checked in by sjamaan, 11 years ago

Remove bogus space in example

File size: 7.9 KB
Line 
1[[tags: egg]]
2
3== fancypants
4
5[[toc:]]
6
7=== Description
8
9
10
11=== Author
12
13[[Peter Bex]]
14
15=== Requirements
16
17This egg has no dependencies, but in order to use it you will need
18[[sxml-transforms]].
19
20=== Documentation
21
22Fancypants is a fairly simple set of functions plus an SXSLT
23ruleset to automagically convert SXML with plain-ASCII strings
24to typographically enhanced Unicode strings.  Ligatures are
25added and quotes are ''educated'' ie, opening quotes
26are curled to the left while closing quotes are curled the
27other way.  An example piece of SXML:
28
29<enscript highlight=scheme>
30(sxml-apply-rules
31  '(blockquote "\"The affable Estonian wasn't fired\","
32               " said the --- strangely afflicted ---"
33               " flying monkey at the office.")
34  (make-fancy-rules)
35  (make-smart-quote-rules))
36</enscript>
37
38When rendered, looks like the following:
39
40<nowiki><blockquote> &#x201c;The a&#xfb00;able Estonian wasn&#x2019;t &#xfb01;red&#x201d;, said the &mdash; strangely a&#xfb04;icted &mdash; &#xfb02;ying monkey at the o&#xfb03;ce.</blockquote></nowiki>
41
42Which looks like this without using fancypants:
43
44<nowiki><blockquote>"The affable Estonian wasn't fired", said the --- strangely afflicted --- flying monkey at the office.</blockquote></nowiki>
45
46As you can see, the quotes are curled correctly, the three minuses are
47converted to real ''emdashes'' and the 'fi', 'ffl', 'fl' and 'ff'
48characters are replaced by ligatures that merge the characters in a
49nice way.
50
51'''A word of warning''': How the ligatures are displayed depends
52heavily on the particular font being used and the implementation of
53the fonts.  For example, on a Mac, most
54[[http://en.wikipedia.org/wiki/Core_fonts_for_the_Web|MS Corefonts]]
55are apparently modified by Apple to support all ligatures, while the
56basic Corefonts by Microsoft (as found under Windows and many Unix
57installations) are lacking ligatures in most fonts.  Consider this
58before using Fancypants' ligature capability (the fi and ff ligatures
59are reasonably safe to use in most cases, though).  Testing on a
60number of platforms is, unfortunately, still a good idea while doing
61webdevelopment.
62
63Fancypants was inspired by [[http://daringfireball.net/projects/smartypants/|SmartyPants]] and, more specifically, [[http://www.cs.wisc.edu/~wolfson/ligatures.html|Mikhail Wolfson's ligatures hack for SmartyPants]].
64
65==== Rulesets
66
67There are two rulesets: one for auto-conversion of ligatures and other
68types of character combinations to Unicode and one for smartening
69quotes.  Both rulesets are generated by functions.
70
71<procedure>(make-fancy-rules [exceptions default-exceptions] [character-map full-map])</procedure>
72
73Create a ruleset that performs ASCII->Unicode mappings for all entries
74in the {{character-map}} argument.
75
76Please note that the order matters because the replacement algorithm
77employes a nongreedy search.  Place prefixes of other matches after
78them and there is no problem.  The symbols in {{exceptions}} are the
79tags to leave alone. (ie, nothing below these is fancified)
80
81<procedure>(make-smart-quote-rules [exceptions default-exceptions] [quotes all-quotes])</procedure>
82
83Create a ruleset that educates quotes.  {{quotes}} defines the
84strategy of how to translate quotes to smart quotes.  See the
85documentation for {{all-quotes}} for more info on the structure of
86this argument.  Please note that here, the order doesn't matter
87because the replacement algorithm uses simple regexes.  The symbols in
88{{exceptions}} are the tags to leave alone. (ie, under these nothing
89has its quotes changes)
90
91==== Constants
92
93<constant>default-exceptions</constant>
94
95This constant is a list of all the tags (symbols) that are ignored by
96default.
97 
98These are: {{(head script pre code kbd samp @)}}.
99
100<constant>default-ligature-map</constant>
101
102An alist of default ASCII sequences that are translated to ligatures
103by {{make-fancy-rules}}.
104
105Contains mappings for 'ffi', 'ffl', 'ff', 'fi', 'fl' and 'ft'.  The
106mapping for 'st' is intentionally left out because this ligature is
107too elaborate to use in body copy.  You could easily define a ruleset
108for eg headings that does include the 'st' ligature (it's Unicode
109character fb06).
110
111<constant>default-punctuation-map</constant>
112
113An alist of default ASCII punctuation sequences to translate to
114'fancy' Unicode versions.  Contains mappings for
115'<nowiki>...</nowiki>' => '<nowiki>&#x2026;</nowiki>',
116'<nowiki>..</nowiki>' => '<nowiki>&#x2025;</nowiki>',
117'<nowiki>. . .</nowiki>' => '<nowiki>&#x2026;</nowiki>',
118'<nowiki>---</nowiki>' => '<nowiki>&mdash;</nowiki>' and
119'<nowiki>--</nowiki>' => '<nowiki>&ndash;</nowiki>'.
120
121<constant>default-arrow-map</constant>
122
123An alist of default ASCII sequences to translate to 'fancy' Unicode
124versions.  This contains several types of arrows.  Useful mostly for
125mathematical texts and 'evaluates to' examples.
126
127<constant>default-map</constant>
128
129The default map to use for fancifying text.  This is simply a
130concatenation of {{default-ligature-map}}, {{default-punctuation-map}}
131and {{default-arrow-map}}.
132
133<constant>all-quotes</constant>
134
135The quote characters in here to be translated by
136{{make-smart-quotes}}.  Remove any you don't want to have handled.
137 
138The structure of an entry in this list is:
139
140  (pre match post how counts?)
141
142{{pre}} is the part of the string that's before the quote to match,
143{{post}} is the string that is after the match.  These
144are all irregex literals.
145
146{{how}} is one of the following symbols: {{single}}, {{double}},
147{{single-open}}, {{double-open}}, {{single-close}} or
148{{double-close}}.
149
150{{counts?}} is a boolean describing whether the quote should influence
151the nesting of subsequent quotes or not.  (ie, "isn't" => #f, since
152the ' is not a quote which matches a preceding quote or which is
153matched by a subsequent quote).
154
155==== Helper procedures
156
157These procedures are used internally by Fancypants, but
158they are probably useful enough to export, so here they are.
159
160<procedure>(fancify string character-map)</procedure>
161
162Perform simple substitution of all ASCII character strings in the
163{{character-map}} alist to their Unicode character within {{string}}.
164
165<procedure>(smarten-quotes sxml quotes exceptions)</procedure>
166
167Smarten the {{sxml}}.  Translates only the strings in the {{quotes}}
168argument, and skips all tag names in the {{exceptions}} list
169
170
171=== Changelog
172
173* 0.3 Ported to Chicken 4 and use irregex's SRE syntax so regexes can be composed
174* 0.2 Added testsuite, removed useless syntax-case dependency
175* 0.1 initial release.
176
177=== License
178
179  Copyright (c) 2006-2009, Peter Bex (peter.bex@xs4all.nl)
180  All rights reserved.
181 
182  Redistribution and use in source and binary forms, with or without
183  modification, are permitted provided that the following conditions
184  are met:
185  1. Redistributions of source code must retain the above copyright
186     notice, this list of conditions and the following disclaimer.
187  2. Redistributions in binary form must reproduce the above copyright
188     notice, this list of conditions and the following disclaimer in the
189     documentation and/or other materials provided with the distribution.
190  3. Neither the name of author nor the names of any contributors may
191     be used to endorse or promote products derived from this software
192     without specific prior written permission.
193 
194  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
195  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
196  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
197  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
198  HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
199  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
200  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
201  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
202  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
203  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
204  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.