source: project/wiki/edit-help @ 36676

Last change on this file since 36676 was 36643, checked in by Mario Domenech Goulart, 15 months ago

edit-help: fix link to CHICKEN logo

File size: 9.5 KB
Line 
1== Editing help
2
3[[toc:]]
4
5=== Introduction
6
7This wiki uses a simplified version of the wiki syntax used by
8[[http://wiki.freaks-unidos.net/svnwiki|svnwiki]].  Below you will
9find an explanation of the subset that's supported by this wiki:
10
11=== Text Formatting
12
13==== Creating a paragraph
14
15To create a paragraph simply enter the text. You can place a single
16newline anywhere in your paragraph and it will have no effect.
17
18To split a paragraph use two consecutive newlines (an empty line).
19
20The 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
30To 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
37If you use two equal signs, you will create a top-level title.  The more
38equal signs you use, the less important your title will be.
39The levels correspond to HTML's {{<h2>}} up to {{<h6>}} tags. The first
40level is reserved for use by the wiki itself.
41
42The very first title will be used as the page title of the entire wiki page.
43This usually appears in your browser's window title and in the search
44results of a search engine so it's important to choose a good title!
45
46This wiki does ''not'' support HTML {{<h1>}}..{{<h6>}} syntax for headings.
47
48=== Font styles (bold, italics, technical)
49
50To create '''bold''' text, use three apostrophes ('), as in: <nowiki>'''bold'''</nowiki>.  Use two for ''italics'': <nowiki>''italics''</nowiki>.
51For {{type-written text}}, which is useful for technical documentation, use this syntax: <nowiki>{{text}}</nowiki>.
52
53Bold 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
55See also the section below about [[#marking-up-code|marking up code]] for
56how 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
62If you want to show the table of contents of an article, use the following
63code:
64
65 [[toc:]]
66
67This will be replaced with the table of contents.  You can see an example at
68the beginning of this page.
69
70=== Lists of items
71
72You can create lists of bullets or numbers by starting your lines with
73asterisks 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
83The 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
93As you can see, you can mix bullets and numbered lists any way you want.
94
95=== Lists of Definitions
96
97You can create a list of definitions by using multiple lines with the
98following syntax:
99
100 ; TERM : DEFINITION
101
102This is useful to give a list of terms along with their respective
103definitions.
104
105Example:
106
107 ; Lassie : A very intelligent dog.
108 ; Garfield : A pessimistic cat.
109 ; Tux : A fearsome pinguin.
110
111This 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
119You can create a table using the standard HTML syntax, based on the
120HTML {{<table>}} tag.
121
122Example:
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
131This 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
140This syntax is rather restricted and clumsy; it is hoped that in a
141future version there will be better syntax for tables.
142
143=== Horizontal dividing line
144
145You can include an horizontal dividing line with the following markup:
146
147 ----
148
149This is shown as:
150
151----
152
153
154== Creating Links
155
156To create links use ''<nowiki>[[dst]]</nowiki>'', where ''dst'' is the
157link target.  You can use relative or absolute URLs; a relative URL
158will link to a page at the same level.  ''dst'' is used unchanged as the descriptive
159text, but the link target will be lowercased, stripped of special characters,
160and have spaces changed to hyphens.
161
162If 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
165is used without change.
166
167To 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
173To 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
180Here 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
192To include images in your articles use the following text:
193
194''<nowiki>[[image:URL|ALT]]</nowiki>''
195
196Here you'll need to replace ''URL'' with the URL of your image and ''ALT'' with a simple description of the image.
197
198Example:
199''<nowiki>[[image:http://www.call-cc.org/pictures/wiki/logos/chicken-small.png|CHICKEN logo]]</nowiki>''
200
201Renders this:
202
203[[image:http://www.call-cc.org/pictures/wiki/logos/chicken-small.png|CHICKEN logo]]
204
205If 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
211You 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
226is shown as:
227
228<enscript highlight="c">
229static void
230pinst_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
243Sometimes you don't want any fancy formatting or interpretation at
244all, you just want to dump a block of preformatted text as-is onto a
245wiki page.
246
247Examples include license statements, transcripts of shell sessions,
248code in alien languages not supported by colorize or when you're
249frustrated by the wiki because it keeps interpreting what you're
250trying to put on a page.
251
252This is easily done by simply prefixing each line of the text you are
253pasting by at least one space.
254
255 Like this!
256
257=== Escaping wiki interpretation
258
259To include something in a page literally (preventing the wiki from converting it
260to HTML), place it inside a {{<nowiki> ... </nowiki>}} pair.  This currently
261only 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
268The following tags are supported:
269
270* {{procedure}}
271* {{macro}}
272
273Each of these should be used as follows:
274
275  <procedure>(string-append a b ...)</procedure>
276
277This 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
283The 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
296They should be used as follows:
297
298  <string>doctype:xhtml-1.0-strict</string>
299
300This will be rendered roughly as follows:
301
302[string] '''{{doctype:xhtml-1.0-strict}}'''
303
304== Tools
305
306=== Emacs
307
308At [[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.
Note: See TracBrowser for help on using the repository browser.