1 | == Editing help |
---|
2 | |
---|
3 | [[toc:]] |
---|
4 | |
---|
5 | === Introduction |
---|
6 | |
---|
7 | This wiki uses a simplified version of the wiki syntax used by |
---|
8 | [[http://wiki.freaks-unidos.net/svnwiki|svnwiki]]. Below you will |
---|
9 | find an explanation of the subset that's supported by this wiki: |
---|
10 | |
---|
11 | === Text Formatting |
---|
12 | |
---|
13 | ==== Creating a paragraph |
---|
14 | |
---|
15 | To create a paragraph simply enter the text. You can place a single |
---|
16 | newline anywhere in your paragraph and it will have no effect. |
---|
17 | |
---|
18 | To split a paragraph use two consecutive newlines (an empty line). |
---|
19 | |
---|
20 | The above two paragraphs could have been written as: |
---|
21 | |
---|
22 | To create a paragraph simply enter the text. |
---|
23 | You can place a single newline anywhere in |
---|
24 | your paragraph and it will have no effect. |
---|
25 | |
---|
26 | To split a paragraph use two consecutive newlines (an empty line). |
---|
27 | |
---|
28 | === Creating titles |
---|
29 | |
---|
30 | To create a title, use a line starting with two, three, four or five equal signs: |
---|
31 | |
---|
32 | == Title Name |
---|
33 | === Sub-title Name |
---|
34 | ==== Sub-sub-title Name |
---|
35 | ===== Sub-sub-sub-title Name |
---|
36 | |
---|
37 | If you use two equal signs, you will create a top-level title. The more |
---|
38 | equal signs you use, the less important your title will be. |
---|
39 | The levels correspond to HTML's {{<h2>}} up to {{<h6>}} tags. The first |
---|
40 | level is reserved for use by the wiki itself. |
---|
41 | |
---|
42 | The very first title will be used as the page title of the entire wiki page. |
---|
43 | This usually appears in your browser's window title and in the search |
---|
44 | results of a search engine so it's important to choose a good title! |
---|
45 | |
---|
46 | This wiki does ''not'' support HTML {{<h1>}}..{{<h6>}} syntax for headings. |
---|
47 | |
---|
48 | === Font styles (bold, italics, technical) |
---|
49 | |
---|
50 | To create '''bold''' text, use three apostrophes ('), as in: <nowiki>'''bold'''</nowiki>. Use two for ''italics'': <nowiki>''italics''</nowiki>. |
---|
51 | For {{type-written text}}, which is useful for technical documentation, use this syntax: <nowiki>{{text}}</nowiki>. |
---|
52 | |
---|
53 | Bold and italics can be nested, but type-written text is treated as-is. This means <nowiki>''{{foo}}''</nowiki> works but <nowiki>{{''foo''}}</nowiki> does not. This is mainly for convenience, because often type-written text is used for identifiers and other programming-like material which can often contain strange sigils that might otherwise affect the wiki. |
---|
54 | |
---|
55 | See also the section below about [[#marking-up-code|marking up code]] for |
---|
56 | how to mark up entire ''blocks'' of program code or technical output. |
---|
57 | |
---|
58 | == Organizing your article (Table of contents, lists, tables, horizontal lines) |
---|
59 | |
---|
60 | === Table of Contents |
---|
61 | |
---|
62 | If you want to show the table of contents of an article, use the following |
---|
63 | code: |
---|
64 | |
---|
65 | [[toc:]] |
---|
66 | |
---|
67 | This will be replaced with the table of contents. You can see an example at |
---|
68 | the beginning of this page. |
---|
69 | |
---|
70 | === Lists of items |
---|
71 | |
---|
72 | You can create lists of bullets or numbers by starting your lines with |
---|
73 | asterisks or number signs: |
---|
74 | |
---|
75 | * Some item |
---|
76 | * Another item |
---|
77 | ** A sub item |
---|
78 | ** Another sub item |
---|
79 | **# A numbered sub sub item |
---|
80 | **# Another numbered sub sub item |
---|
81 | * The last item |
---|
82 | |
---|
83 | The above list will be rendered as: |
---|
84 | |
---|
85 | * Some item |
---|
86 | * Another item |
---|
87 | ** A sub item |
---|
88 | ** Another sub item |
---|
89 | **# A numbered sub sub item |
---|
90 | **# Another numbered sub sub item |
---|
91 | * The last item |
---|
92 | |
---|
93 | As you can see, you can mix bullets and numbered lists any way you want. |
---|
94 | |
---|
95 | === Lists of Definitions |
---|
96 | |
---|
97 | You can create a list of definitions by using multiple lines with the |
---|
98 | following syntax: |
---|
99 | |
---|
100 | ; TERM : DEFINITION |
---|
101 | |
---|
102 | This is useful to give a list of terms along with their respective |
---|
103 | definitions. |
---|
104 | |
---|
105 | Example: |
---|
106 | |
---|
107 | ; Lassie : A very intelligent dog. |
---|
108 | ; Garfield : A pessimistic cat. |
---|
109 | ; Tux : A fearsome pinguin. |
---|
110 | |
---|
111 | This list is shown as: |
---|
112 | |
---|
113 | ; Lassie : A very intelligent dog. |
---|
114 | ; Garfield : A pessimistic cat. |
---|
115 | ; Tux : A fearsome pinguin. |
---|
116 | |
---|
117 | === Using tables |
---|
118 | |
---|
119 | You can create a table using the standard HTML syntax, based on the |
---|
120 | HTML {{<table>}} tag. |
---|
121 | |
---|
122 | Example: |
---|
123 | |
---|
124 | <table> |
---|
125 | <tr><th>Country</th><th>Number of cities</th></tr> |
---|
126 | <tr><td>Colombia</td><td>17</td></tr> |
---|
127 | <tr><td>Argentina</td><td>12</td></tr> |
---|
128 | <tr><td>Brasil</td><td>31</td></tr> |
---|
129 | </table> |
---|
130 | |
---|
131 | This is shown as: |
---|
132 | |
---|
133 | <table> |
---|
134 | <tr><th>Country</th><th>Number of cities</th></tr> |
---|
135 | <tr><td>Colombia</td><td>17</td></tr> |
---|
136 | <tr><td>Argentina</td><td>12</td></tr> |
---|
137 | <tr><td>Brasil</td><td>31</td></tr> |
---|
138 | </table> |
---|
139 | |
---|
140 | This syntax is rather restricted and clumsy; it is hoped that in a |
---|
141 | future version there will be better syntax for tables. |
---|
142 | |
---|
143 | === Horizontal dividing line |
---|
144 | |
---|
145 | You can include an horizontal dividing line with the following markup: |
---|
146 | |
---|
147 | ---- |
---|
148 | |
---|
149 | This is shown as: |
---|
150 | |
---|
151 | ---- |
---|
152 | |
---|
153 | |
---|
154 | == Creating Links |
---|
155 | |
---|
156 | To create links use ''<nowiki>[[dst]]</nowiki>'', where ''dst'' is the |
---|
157 | link target. You can use relative or absolute URLs; a relative URL |
---|
158 | will link to a page at the same level. ''dst'' is used unchanged as the descriptive |
---|
159 | text, but the link target will be lowercased, stripped of special characters, |
---|
160 | and have spaces changed to hyphens. |
---|
161 | |
---|
162 | If you want your link to display a text other than its target, use |
---|
163 | ''<nowiki>[[dst|Some text]]</nowiki>''. This will be shown as: |
---|
164 | [[dst|Some text]]. When descriptive text is provided, the link target |
---|
165 | is used without change. |
---|
166 | |
---|
167 | To link to an egg, use |
---|
168 | |
---|
169 | * <nowiki>[[name]] from within another egg page</nowiki> |
---|
170 | * <nowiki>[[/egg/name|name]] from outside an egg page</nowiki> |
---|
171 | * <nowiki>[[/eggref/3/name|name]] for an egg for a specific CHICKEN version (here, 3)</nowiki> |
---|
172 | |
---|
173 | To link to a manual page, use |
---|
174 | |
---|
175 | * <nowiki>[[/manual/Page name|Page name]] from outside a manual page</nowiki> |
---|
176 | * <nowiki>[[/man/3/name|name]] for a man page for a specific CHICKEN version (here, 3)</nowiki> |
---|
177 | |
---|
178 | ''Note'': You can't use the plain <nowiki>[[Page name]]</nowiki> syntax for manual pages, as the page URL will be lowercased and hyphenated. |
---|
179 | |
---|
180 | Here are some examples. Since this page is neither an egg nor a man page, we must use the full /egg or /manual syntax for those: |
---|
181 | |
---|
182 | * <nowiki>[[http://www.call-cc.org/]]</nowiki>: [[http://www.call-cc.org/]] |
---|
183 | * <nowiki>[[http://www.call-cc.org/|The CHICKEN wiki]]</nowiki>: [[http://www.call-cc.org/|The CHICKEN wiki]] |
---|
184 | * <nowiki>[[/users/felix-winkelmann|Felix]]</nowiki>: [[/users/felix-winkelmann|Felix]] |
---|
185 | * <nowiki>[[/manual/Unit posix|Unit posix]]</nowiki>: [[/manual/Unit posix|Unit posix]] |
---|
186 | * <nowiki>[[/egg/awful|the awful egg]]</nowiki> : [[/egg/awful|the awful egg]] |
---|
187 | * <nowiki>[[Internals]]</nowiki> : [[Internals]] |
---|
188 | * <nowiki>[[/tips and tricks|Tips and tricks]]</nowiki> : [[/tips and tricks|Tips and tricks]] |
---|
189 | |
---|
190 | == Including Images |
---|
191 | |
---|
192 | To include images in your articles use the following text: |
---|
193 | |
---|
194 | ''<nowiki>[[image:URL|ALT]]</nowiki>'' |
---|
195 | |
---|
196 | Here you'll need to replace ''URL'' with the URL of your image and ''ALT'' with a simple description of the image. |
---|
197 | |
---|
198 | Example: |
---|
199 | ''<nowiki>[[image:http://www.call-with-current-continuation.org/chicken-small.png|CHICKEN logo]]</nowiki>'' |
---|
200 | |
---|
201 | Renders this: |
---|
202 | |
---|
203 | [[image:http://www.call-with-current-continuation.org/chicken-small.png|CHICKEN logo]] |
---|
204 | |
---|
205 | If you keep your images in the wiki repository, the base for the absolute URL is: {{http://code.call-cc.org/svn/chicken-eggs/wiki/}}. For example, an image {{egg-image-1.png}} uploaded into {{wiki/eggref/4}} has URL {{http://code.call-cc.org/svn/chicken-eggs/wiki/eggref/4/egg-image-1.png}} |
---|
206 | |
---|
207 | == Marking up code |
---|
208 | |
---|
209 | === Syntax coloring |
---|
210 | |
---|
211 | You can embbed code or information in many file formats or programming languages; the wiki will use the [[/egg/colorize|colorize]] egg to add syntax highlighting to it. You can use any language supported by colorize. This is a growing list. |
---|
212 | |
---|
213 | <enscript highlight="c"> |
---|
214 | static void |
---|
215 | pinst_check () |
---|
216 | { |
---|
217 | pid_t pinst = pinst_find(); |
---|
218 | if (pinst != -1 && kill(pinst, 0) != -1) |
---|
219 | printf("%s: server alive (%d)\n", program_name, pinst); |
---|
220 | else |
---|
221 | printf("%s: server is not running\n", program_name); |
---|
222 | exit(EXIT_SUCCESS); |
---|
223 | } |
---|
224 | </enscript> |
---|
225 | |
---|
226 | is shown as: |
---|
227 | |
---|
228 | <enscript highlight="c"> |
---|
229 | static void |
---|
230 | pinst_check () |
---|
231 | { |
---|
232 | pid_t pinst = pinst_find(); |
---|
233 | if (pinst != -1 && kill(pinst, 0) != -1) |
---|
234 | printf("%s: server alive (%d)\n", program_name, pinst); |
---|
235 | else |
---|
236 | printf("%s: server is not running\n", program_name); |
---|
237 | exit(EXIT_SUCCESS); |
---|
238 | } |
---|
239 | </enscript> |
---|
240 | |
---|
241 | === Literal blocks of preformatted text |
---|
242 | |
---|
243 | Sometimes you don't want any fancy formatting or interpretation at |
---|
244 | all, you just want to dump a block of preformatted text as-is onto a |
---|
245 | wiki page. |
---|
246 | |
---|
247 | Examples include license statements, transcripts of shell sessions, |
---|
248 | code in alien languages not supported by colorize or when you're |
---|
249 | frustrated by the wiki because it keeps interpreting what you're |
---|
250 | trying to put on a page. |
---|
251 | |
---|
252 | This is easily done by simply prefixing each line of the text you are |
---|
253 | pasting by at least one space. |
---|
254 | |
---|
255 | Like this! |
---|
256 | |
---|
257 | === Escaping wiki interpretation |
---|
258 | |
---|
259 | To include something in a page literally (preventing the wiki from converting it |
---|
260 | to HTML), place it inside a {{<nowiki> ... </nowiki>}} pair. This currently |
---|
261 | only has an effect on HTML output (not the other outputs supported by [[/egg/multidoc|multidoc]], so please don't rely on it too much. |
---|
262 | |
---|
263 | |
---|
264 | == Extensions for CHICKEN documentation |
---|
265 | |
---|
266 | === Tags for procedure-like definitions |
---|
267 | |
---|
268 | The following tags are supported: |
---|
269 | |
---|
270 | * {{procedure}} |
---|
271 | * {{macro}} |
---|
272 | |
---|
273 | Each of these should be used as follows: |
---|
274 | |
---|
275 | <procedure>(string-append a b ...)</procedure> |
---|
276 | |
---|
277 | This will be roughly rendered as follows (with some divs and spans for easy CSSing): |
---|
278 | |
---|
279 | [procedure] {{(}}'''{{string-append}}'''{{ a b ...)}} |
---|
280 | |
---|
281 | === Tags for other definitions |
---|
282 | |
---|
283 | The following tags are also supported: |
---|
284 | |
---|
285 | * {{read}} |
---|
286 | * {{parameter}} |
---|
287 | * {{record}} |
---|
288 | * {{string}} |
---|
289 | * {{class}} |
---|
290 | * {{method}} |
---|
291 | * {{constant}} |
---|
292 | * {{setter}} |
---|
293 | * {{syntax}} |
---|
294 | * {{type}} |
---|
295 | |
---|
296 | They should be used as follows: |
---|
297 | |
---|
298 | <string>doctype:xhtml-1.0-strict</string> |
---|
299 | |
---|
300 | This will be rendered roughly as follows: |
---|
301 | |
---|
302 | [string] '''{{doctype:xhtml-1.0-strict}}''' |
---|
303 | |
---|
304 | == Tools |
---|
305 | |
---|
306 | === Emacs |
---|
307 | |
---|
308 | At [[https://github.com/mario-goulart/el-chicken-wiki|https://github.com/mario-goulart/el-chicken-wiki]] you can find some Emacs commands to help editing this wiki. |
---|
309 | |
---|
310 | [[https://github.com/wasamasa/svnwiki-mode]] provides a major mode for highlighting buffers using this wiki syntax. |
---|