]> git.wincent.com - wikitext.git/blob - README.rdoc
Change license header from GPL to BSD
[wikitext.git] / README.rdoc
1 The wikitext extension is a fast wikitext-to-HTML translator written
2 in C and packaged as a Ruby extension.
3
4 Usage is straightforward:
5
6  $ irb -r wikitext
7  >> Wikitext::Parser.new.parse("hello world!")
8  => "<p>hello world!</p>\n"
9
10 = Design goals
11
12 I needed a wikitext-to-HTML translator for a Rails application; a number
13 of design goals flowed on from this:
14
15 * _fast_: Rails has a reputation for being slow, so the translator had
16   to be part of the solution, not part of the problem
17 * _efficient_: again, given how much memory Rails likes to use, the
18   translator had to be very memory-efficient
19 * _robust_: on a public-facing web application that had to be up for long
20   periods, the translator had to be stable (no crashes, no resource leaks)
21 * _secure_: again, accepting input from untrusted sources meant that the
22   translator had to sanitize or reject unsafe input
23 * <em>easy to use</em>: for end users, the translator should provide a
24   simple, familiar markup as close as possible to what they already know
25   from other applications (such as MediaWiki, the wiki software that
26   powers Wikipedia)
27 * _forgiving_: wikitext is presentation markup, not source code, so the
28   translator should do a reasonable job of formatting even the most
29   invalid markup rather than giving up
30 * _informative_: when provided invalid markup the translator should
31   fail gracefully and emit HTML that provides useful visual feedback
32   about where the errors are in the input
33 * <em>multilingual-friendly</em>: the translator should handle input beyond
34   printable ASCII in a compatible fashion
35 * _attractive_: the emitted HTML source should be consistent and attractive
36 * <em>valid output</em>: regardless of the input, the translator should
37   always produce valid XHTML output
38 * <em>well-tested</em>: the translator should have a comprehensive test
39   suite to ensure that its behaviour is not only correct but also stable
40   over time
41 * <em>cross-platform</em>: should work identically on Mac OS X, Linux
42   (explicitly tested platforms) and perhaps others as well
43
44 Some notable things that were _not_ design goals:
45
46 * implement _all_ of the MediaWiki syntax (tables etc)
47
48 = Markup
49
50 The markup is very close to that used by MediaWiki, the most popular wiki
51 software and the one that powers Wikipedia.
52
53 == Headings
54
55  = Heading 1 =
56  == Heading 2 ==
57  === Heading 3 ===
58  ==== Heading 4 ====
59  ===== Heading 5 =====
60  ====== Heading 6 ======
61
62 Are marked up as:
63
64  <h1>Heading 1</h1>
65  <h2>Heading 2</h2>
66  <h3>Heading 3</h3>
67  <h4>Heading 4</h4>
68  <h5>Heading 5</h5>
69  <h6>Heading 6</h6>
70
71 == Paragraphs
72
73 Consecutive linebreaks are converted into paragraph breaks.
74
75  This is one paragraph.
76  Another line.
77  
78  And this is another.
79
80 Would be marked up as:
81
82  <p>This is one paragraph. Another line.</p>
83  <p>And this is another.</p>
84
85 == Emphasis, Strong
86
87 Emphasis is marked up as follows:
88
89   ''emphasized''
90
91 Which gets translated into:
92
93   <em>emphasized</em>
94
95 Strong is marked up like this:
96
97   '''strong text'''
98
99 And transformed into:
100
101   <strong>strong text</strong>
102
103 You can nest spans inside one another, provided you don't try to produce
104 invalid HTML (for example, nesting strong inside strong). Here is a valid
105 example:
106
107   '''''foo'' bar''' baz
108
109 This would become:
110
111   <strong><em>foo</em> bar</strong> baz
112
113 Note that the translator emits HTML on the fly, so when it sees the
114 first run of five apostrophes it has no way of knowing what will come
115 afterwards and so doesn't know whether you mean to say "strong em" or
116 "em strong"; it therefore always assumes "strong em". If you wish to
117 force the alternative interpretation you can do one of the following:
118
119  '' '''foo''' bar'' baz (ie. use whitespace)
120  ''<nowiki></nowiki>'''foo''' bar'' baz (ie. insert an empty nowiki span)
121  <em><strong>foo</strong> bar</em> baz (ie. use explicit HTML tags instead)
122  <em>'''foo''' bar</em> baz (ie. use explicit HTML tags instead)
123
124 Note that to avoid ambiguity, the translator will not let you intermix
125 the shorthand style with the literal HTML tag style.
126
127  <em>foo'' (ie. intermixed, invalid)
128
129 == Teletype
130
131 The translator recognizes both standard HTML +tt+ tags and the
132 backtick (`) as a shorthand. These two are equivalent:
133
134   <tt>fixed</tt>
135   `fixed`
136
137 If you need to insert a literal backtick in your text you use a +nowiki+
138 span:
139
140   here follows a literal <nowiki>`</nowiki> backtick
141
142 To avoid ambiguity, the translator will not let you intermix the two
143 styles.
144
145 == +nowiki+ spans
146
147 Already mentioned above, you can use +nowiki+ tags to temporarily disable
148 wikitext markup. As soon as the translator sees the opening +nowiki+ tag
149 it starts emitting a literal copy of everything it sees up until the
150 closing +nowiki+ tag:
151
152   Hello <nowiki>''world''</nowiki>
153
154 Would be emitted as:
155
156   Hello ''world''
157
158 == Blockquotes
159
160   > Hello world!
161   > Bye for now.
162
163 Would be emitted as:
164
165   <blockquote><p>Hello world! Bye for now.</p></blockquote>
166
167 You can nest blockquotes or any other kind of block or span inside
168 blockquotes. For example:
169
170   > first quote
171   >> quote inside a quote
172
173 == Preformatted text
174
175 Any line indented with whitespace will be interpreted as part of a +pre+
176 block. Wikitext markup inside +pre+ blocks has no special meaning. For
177 example, consider the following block indented by a single space:
178
179    // source code listing
180    void foo(void)
181    {
182       x++;
183    }
184
185 Would be translated into:
186
187   <pre>// source code listing
188   void foo(void)
189   {
190     x++;
191   }</pre>
192
193 +pre+ blocks may be nested inside +blockquote+ blocks.
194
195 == Internal links
196
197   [[article title]]
198
199 Would become:
200
201   <a href="/wiki/article_title">article title</a>
202
203 And:
204
205   [[title|link text]]
206
207 Would become:
208
209   <a href="/wiki/article">link text</a>
210
211 See the Parser attributes documentation for how you can override the
212 default link prefix (<em>/wiki/</em> as shown in the example).
213
214 == Alternative blockquote and preformatted block syntax
215
216 For +blockquote+ and +pre+ blocks that go on for many lines it may be
217 more convenient to use the alternative syntax which uses standard
218 HTML tags rather than special prefixes at the beginning of each line.
219
220   <blockquote>This is
221   a blockquote!</blockquote>
222   
223   <pre>And this is
224   preformatted text</pre>
225
226 +blockquote+ and +pre+ blocks may nest inside other +blockquote+
227 blocks.
228
229 Note that to avoid ambiguity, the translator will not let you intermix
230 the two styles (HTML markup and wikitext markup).
231
232 == External links
233
234   [http://example.com/ this site]
235
236 Would become:
237
238   <a href="http://example.com/" class="external">this site</a>
239
240 See the Parser attributes documentation for information on overriding
241 the default external link class (+external+ in this example).
242
243 Note that in addition to providing a fully-qualified URL including a
244 protocol (such as "http://" or "ftp://") you also have the option of
245 using an unqualified "path"-style URL. This is useful for making
246 links to other pages still on the same site, but outside of the wiki:
247
248   [/issues/1024 ticket #1024]
249
250 Would become:
251
252   <a href="/issues/1024">ticket #1024</a>
253
254 Note that no "external" class is included in the generated link.
255
256 To avoid false positives, what constitutes a "path" is
257 narrowly-defined as a string that begins with a slash, optionally
258 followed by zero or more "path components" consisting of upper and
259 lowercase letters, numbers, underscores, hyphens or periods. Path
260 components are separated by a slash, and the trailing slash after
261 the last path component is optional.
262
263 == Images
264
265   {{foo.png}}
266
267 Would become:
268
269   <img src="/images/foo.png" alt="foo.png" />
270
271 You can override the "/images/" prefix using the +img_prefix+ attribute
272 of the Parser.
273
274 You can also specify "absolute" image "src" attributes regardless of
275 the current prefix setting by starting the image path with a forward
276 slash; that is:
277
278   {{/foo.png}}
279
280 Would become:
281
282   <img src="/foo.png" alt="/foo.png" />
283
284 = Links
285
286 * RubyForge project page: http://rubyforge.org/projects/wikitext
287 * RDoc: http://wikitext.rubyforge.org
288 * Source: http://git.wincent.com/wikitext.git
289 * Author/maintainer: Wincent Colaiuta (win@wincent.com, http://wincent.com)
290
291 = License
292
293 Copyright 2007-2009 Wincent Colaiuta. All rights reserved.
294
295 Redistribution and use in source and binary forms, with or without
296 modification, are permitted provided that the following conditions are met:
297
298 1. Redistributions of source code must retain the above copyright notice,
299    this list of conditions and the following disclaimer.
300 2. Redistributions in binary form must reproduce the above copyright notice,
301    this list of conditions and the following disclaimer in the documentation
302    and/or other materials provided with the distribution.
303
304 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
305 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
306 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
307 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
308 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
309 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
310 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
311 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
312 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
313 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
314 POSSIBILITY OF SUCH DAMAGE.
315
316 = Feedback
317
318 Please let me know if you're using the wikitext extension in your project.
319 If you have any bug reports or feature requests please open a ticket in
320 the issue tracker at https://wincent.com/issues.
321
322 = Donations
323
324 If you find this extension useful, please consider making a donation via
325 PayPal to win@wincent.com.