source: project/release/3/fancypants/fancypants.html @ 13974

Last change on this file since 13974 was 13974, checked in by sjamaan, 10 years ago

Add a testsuite and update to 0.2

File size: 12.7 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2<!-- Generated by eggdoc Revision: 1.20  -->
3<html>
4<head>
5<title>Eggs Unlimited - fancypants</title><style type="text/css"> <!--
6      CODE {
7            color: #666666;
8          }
9/*   DT.definition EM { font-weight: bold; font-style: normal; } */
10
11     DT.definition { 
12                   background: #eee;
13                   color: black;
14                   padding: 0.2em 1em 0.2em 0.7em;
15                   margin-left: 0.2em;
16border: 1px solid #bbc;
17                   font-family: "Andale Mono", monospace;
18                   /* font-size: 1.2em; */
19                   
20                 }
21     DD {
22                   margin-top: 0.8em;
23                   margin-bottom: 0.8em;
24     }
25     DIV.subsection {
26                    border-top: 1px solid #448;
27                    padding-left: 1em;
28                    margin-bottom: 1.2em;
29     }
30     DIV.subsubsection {
31                    border-top: 1px dotted #99c;
32                    /* border-left: 1px solid #99c; */
33                    padding-left: 1em;
34                    margin-bottom: 1.2em;
35     }
36     DIV.subsubsubsection {
37                    border-top: 1px solid #ddf;
38                    padding-left: 1em;
39                    margin-bottom: 1.2em;
40     }
41
42         DIV.section {
43                 margin-bottom: 1.5em;
44         }
45         a:link {
46                 color: #336;
47         }
48         a:visited { color: #666; }
49         a:active  { color: #966; }
50         a:hover   { color: #669; }
51         body { margin: 0; padding: 0; background: #fff; color: #000; font: 9pt "Lucida Grande", "Verdana", sans-serif; }
52         H2 {
53                 background: #336;
54                 color: #fff;
55                 padding-top: 0.5em;
56                 padding-bottom: 0.5em;
57                 padding-left: 16px;
58                 margin: 0 0 1em 0;
59        }
60        UL LI {
61                list-style: none;
62        }
63        TT {
64                font-family: "Andale Mono", monospace;
65                /* font-size: 1.2em; */
66        }
67        H3 {
68                color: #113;
69                margin-bottom: 0.5em;
70        }
71        H4, H5, H6 {
72                color: #113;
73                margin-bottom: 1.0em;
74        }
75        H5 {
76                font-weight: normal;
77                font-style: italic;
78                font-size: 100%;
79                margin-top: 1.2em;
80        }
81        H6 {
82                font-weight: bold;
83                font-size: 85%;
84                margin-top: 1.2em;
85        }
86     DIV#eggheader {
87         text-align: center;
88                 float: right;
89                 margin-right: 2em;
90     }
91     DIV#header IMG {
92            /* display: block; margin-left: auto; margin-right: auto;  */
93            /* float: right; */
94            border: none;  /* firefox */
95     }
96     DIV#footer {
97                background: #bbd;
98                padding: 0.7em ;
99                border-top: 1px solid #cce;
100     }
101     DIV#footer hr {
102                display: none;
103     }
104     DIV#footer a {
105                float: left;
106     }
107     DIV#revision-history {
108         float: right;
109     }
110     
111     DIV#body {
112                 margin: 1em 1em 1em 16px;
113         }
114
115     DIV#examples PRE {
116       background: #eef;
117       padding: 0.1em;
118       border: 1px solid #aac;
119     }
120     PRE#license, DIV#examples PRE {
121       padding: 0.5em;
122     }
123     DIV#examples PRE {
124       /* font-size: 85%; */
125     }
126     PRE { font-family: "Andale Mono", monospace; }
127     TABLE {
128       background: #eef;
129       padding: 0.2em;
130       border: 1px solid #aac;
131       border-collapse: collapse;
132       width: 100%;
133     }
134     TABLE.symbol-table TD.symbol {
135          width: 15em;
136          font-family: "Andale Mono", monospace;
137          /* font-size: 1.2em; */
138     }
139     TH {
140       text-align: left;
141       border-bottom: 1px solid #aac;
142       padding: 0.25em 0.5em 0.25em 0.5em;
143     } 
144     TD { padding: 0.25em 0.5em 0.25em 0.5em; }
145     --></style></head>
146<body>
147<div id="header">
148<h2>fancypants</h2>
149<div id="eggheader"><a href="index.html">
150<img src="egg.jpg" alt="[Picture of an egg]" /></a></div></div>
151<div id="body">
152<div class="section">
153<h3>Description</h3>Automatic ASCII smart quotes and ligature handling for SXML</div>
154<div class="section">
155<h3>Author</h3><a href="mailto:peter.bex@xs4all.nl">Peter Bex</a></div>
156<div class="section">
157<h3>Version</h3>
158<ul>
159<li>0.2 Added testsuite, removed useless syntax-case dependency</li>
160<li>0.1 initial release.</li></ul></div>
161<div class="section">
162<h3>Requires</h3>
163<ul>
164<li><a href="sxml-transforms.html">sxml-transforms</a></li></ul></div>
165<div class="section">
166<h3>Download</h3><a href="fancypants.egg">fancypants.egg</a></div>
167<div class="section">
168<h3>Documentation</h3>
169<p>Fancypants is a fairly simple set of functions plus an SXSLT ruleset to automagically convert SXML with plain-ASCII strings to typographically enhanced Unicode strings.  Ligatures are added and quotes are <em>educated</em> ie, opening quotes are curled to the left while closing quotes are curled the other way.  An example piece of SXML:</p>
170<pre><code>(sxml-apply-rules
171  '(blockquote &quot;\&quot;The affable Estonian wasn't fired\&quot;,&quot;
172               &quot; said the --- strangely afflicted ---&quot;
173               &quot; flying monkey at the office.&quot;)
174  (make-fancy-rules)
175  (make-smart-quote-rules))</code></pre>
176<p>When rendered, looks like the following:</p>
177<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>
178<p>Which looks like this without using fancypants:</p>
179<blockquote>&quot;The affable Estonian wasn't fired&quot;, said the --- strangely afflicted --- flying monkey at the office.</blockquote>
180<p>As you can see, the quotes are curled correctly, the three minuses are converted to real <em>emdashes</em> and the 'fi', 'ffl', 'fl' and 'ff' characters are replaced by ligatures that merge the characters in a nice way.</p>
181<p>A word of warning: How the ligatures are displayed depends heavily on the particular font being used and the implementation of the fonts.  For example, on a Mac, most <a href="http://en.wikipedia.org/wiki/Core_fonts_for_the_Web">MS Corefonts</a> are apparently modified by Apple to support all ligatures, while the basic Corefonts by Microsoft (as found under Windows and many Unix installations) are lacking ligatures in most fonts.  Consider this before using Fancypants' ligature capability (the fi and ff ligatures are reasonably safe to use in most cases, though).  Testing on a number of platforms is, unfortunately, still a good idea while doing webdevelopment.</p>
182<p>Fancypants was inspired by <a href="http://daringfireball.net/projects/smartypants/">SmartyPants</a> and, more specifically, <a href="http://www.cs.wisc.edu/~wolfson/ligatures.html">Mikhail Wolfson's ligatures hack.</a></p>
183<div class="subsection">
184<h4>Rulesets</h4>
185<p>There are two rulesets: one for auto-conversion of ligatures and other types of character combinations to Unicode and one  for smartening quotes.  Both rulesets are generated by functions.</p>
186<dt class="definition"><strong>procedure:</strong> (make-fancy-rules [exceptions default-exceptions] [character-map full-map])</dt>
187<dd>Create a ruleset that performs ASCII-&gt;Unicode mappings for all entries in the <code>character-map</code> argument. Please note that the order matters because the replacement algorithm employes a nongreedy search.  Place prefixes of other matches after them and there is no problem. The symbols in <code>exceptions</code> are the tags to leave alone. (ie, nothing below these is fancified)</dd>
188<dt class="definition"><strong>procedure:</strong> (make-smart-quote-rules [exceptions default-exceptions] [quotes all-quotes])</dt>
189<dd>Create a ruleset that educates quotes. <code>quotes</code> defines the strategy of how to translate quotes to smart quotes.  See the documentation for <code>all-quotes</code> for more info on the structure of this argument.  Please note that here, the order doesn't matter because the replacement algorithm uses simple regexes. The symbols in <code>exceptions</code> are the tags to leave alone. (ie, under these nothing has its quotes changes)</dd></div>
190<div class="subsection">
191<h4>Constants</h4>
192<dt class="definition"><strong>constant:</strong> default-exceptions</dt>
193<dd>This constant is a list of all the tags (symbols) that are ignored by default. These are:  <code>(head script pre code kbd samp @)</code></dd>
194<dt class="definition"><strong>constant:</strong> default-ligature-map</dt>
195<dd>An alist of default ASCII sequences that are translated to ligatures by <code>make-fancy-rules</code>. Contains mappings for 'ffi', 'ffl', 'ff', 'fi', 'fl' and 'ft'.  The mapping for 'st' is intentionally left out because this ligature is too elaborate to use in body copy.  You could easily define a ruleset for eg headings that does include the 'st' ligature (it's Unicode character fb06).</dd>
196<dt class="definition"><strong>constant:</strong> default-punctuation-map</dt>
197<dd>An alist of default ASCII punctuation sequences to translate to 'fancy' Unicode versions.  Contains mappings for '...' =&gt; '&#x2026;', '..' =&gt; '&#x2025;', '. . .' =&gt; '&#x2026;', '---' =&gt; '&mdash;' and '--' =&gt; '&ndash;'.</dd>
198<dt class="definition"><strong>constant:</strong> default-arrow-map</dt>
199<dd>An alist of default ASCII sequences to translate to 'fancy' Unicode versions.  This contains several types of arrows. Useful mostly for mathematical texts and 'evaluates to' examples.</dd>
200<dt class="definition"><strong>constant:</strong> default-map</dt>
201<dd>The default map to use for fancifying text.  This is simply a concatenation of <code>default-ligature-map</code>, <code>default-punctuation-map</code> and <code>default-arrow-map</code>.</dd>
202<dt class="definition"><strong>constant:</strong> all-quotes</dt>
203<dd>The quote characters in here to be translated by <code>make-smart-quotes</code>.  Remove any you don't want to have handled.The structure of an entry in this list is: <code>(pre match post how counts?)</code>. <code>pre</code> is the part of the string that's before the quote to match, <code>post</code> is the string that is after the match.  These are all regexes, or <code>#f</code>. <code>how</code> is one of: <code>single</code>, <code>double</code>, <code>single-open</code>, <code>double-open</code>, <code>single-close</code> or <code>double-close</code>. <code>counts?</code> is a boolean describing whether the quote should influence the nesting of subsequent quotes or not.  (ie, &quot;isn't&quot; =&gt; #f, since the ' is not a  quote which matches a preceding quote or which is matched by a subsequent quote). Note that you (currently) can't use brackets in these regexes, since that messes up the expected structure of the result of <code>string-search-positions</code>.</dd></div>
204<div class="subsection">
205<h4>Helper functions</h4>
206<p>These functions are used internally by Fancypants, but they are probably useful enough to export, so here they are.</p>
207<dt class="definition"><strong>procedure:</strong> (fancify string character-map)</dt>
208<dd>Perform simple substitution of all ASCII character strings in the <code>character-map</code> alist to their Unicode character within <code>string</code>.</dd>
209<dt class="definition"><strong>procedure:</strong> (smarten-quotes sxml quotes exceptions)</dt>
210<dd>Smarten the <code>sxml</code>.  Translates only the strings in the <code>quotes</code> argument, and skips all tag names in the <code>exceptions</code> list</dd></div></div>
211<div class="section">
212<h3>License</h3>
213<pre id="license">Copyright (c) 2006-2009, Peter Bex (peter.bex@xs4all.nl)
214All rights reserved.
215
216Redistribution and use in source and binary forms, with or without
217modification, are permitted provided that the following conditions
218are met:
2191. Redistributions of source code must retain the above copyright
220   notice, this list of conditions and the following disclaimer.
2212. Redistributions in binary form must reproduce the above copyright
222   notice, this list of conditions and the following disclaimer in the
223   documentation and/or other materials provided with the distribution.
2243. Neither the name of author nor the names of any contributors may
225   be used to endorse or promote products derived from this software
226   without specific prior written permission.
227
228THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
229``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
230LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
231A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
232HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
233SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
234LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
235DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
236THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
237(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
238OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</pre></div></div>
239<div id="footer">
240<hr /><a href="index.html">&lt; Egg index</a>
241<div id="revision-history">$Revision$ $Date$</div>&nbsp;</div></body></html>
Note: See TracBrowser for help on using the repository browser.