]> git.wincent.com - wikitext.git/blob - README.rdoc
Update README for new PRE_START "lang" attribute
[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 +pre+ blocks may also contain a custom +lang+ attribute for the purposes
233 of marking up a block for syntax-highlighting (note that the highlighting
234 itself would be provided by JavaScript in the browser and is not actually
235 part of the wikitext extension). For example:
236
237   <pre lang="ruby">puts @person.name</pre>
238
239 Would be translated into:
240
241   <pre class="ruby-syntax">puts @person.name</pre>
242
243 The +lang+ attribute may only contain letters, so "Objective-C", for
244 example would need to be written as "objc" or similar.
245
246 == External links
247
248   [http://example.com/ this site]
249
250 Would become:
251
252   <a href="http://example.com/" class="external">this site</a>
253
254 See the Parser attributes documentation for information on overriding
255 the default external link class (+external+ in this example).
256
257 Note that in addition to providing a fully-qualified URL including a
258 protocol (such as "http://" or "ftp://") you also have the option of
259 using an unqualified "path"-style URL. This is useful for making
260 links to other pages still on the same site, but outside of the wiki:
261
262   [/issues/1024 ticket #1024]
263
264 Would become:
265
266   <a href="/issues/1024">ticket #1024</a>
267
268 Note that no "external" class is included in the generated link.
269
270 To avoid false positives, what constitutes a "path" is
271 narrowly-defined as a string that begins with a slash, optionally
272 followed by zero or more "path components" consisting of upper and
273 lowercase letters, numbers, underscores, hyphens or periods. Path
274 components are separated by a slash, and the trailing slash after
275 the last path component is optional.
276
277 == Images
278
279   {{foo.png}}
280
281 Would become:
282
283   <img src="/images/foo.png" alt="foo.png" />
284
285 You can override the "/images/" prefix using the +img_prefix+ attribute
286 of the Parser.
287
288 You can also specify "absolute" image "src" attributes regardless of
289 the current prefix setting by starting the image path with a forward
290 slash; that is:
291
292   {{/foo.png}}
293
294 Would become:
295
296   <img src="/foo.png" alt="/foo.png" />
297
298 = Links
299
300 * RubyForge project page: http://rubyforge.org/projects/wikitext
301 * RDoc: http://wikitext.rubyforge.org
302 * Source: http://git.wincent.com/wikitext.git
303 * Author/maintainer: Wincent Colaiuta (win@wincent.com, http://wincent.com)
304
305 = License
306
307 Copyright 2007-2009 Wincent Colaiuta. All rights reserved.
308
309 Redistribution and use in source and binary forms, with or without
310 modification, are permitted provided that the following conditions are met:
311
312 1. Redistributions of source code must retain the above copyright notice,
313    this list of conditions and the following disclaimer.
314 2. Redistributions in binary form must reproduce the above copyright notice,
315    this list of conditions and the following disclaimer in the documentation
316    and/or other materials provided with the distribution.
317
318 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
319 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
320 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
321 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
322 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
323 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
324 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
325 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
326 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
327 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
328 POSSIBILITY OF SUCH DAMAGE.
329
330 = Feedback
331
332 Please let me know if you're using the wikitext extension in your project.
333 If you have any bug reports or feature requests please open a ticket in
334 the issue tracker at https://wincent.com/issues.
335
336 = Donations
337
338 If you find this extension useful, please consider making a donation via
339 PayPal to win@wincent.com.