1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
|
<?xml version='1.0' encoding="UTF-8"?>
<!--
English doc rev. 1.13
-->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="/doc/nl/xml-guide.xml">
<title>Gentoo Linux XML Handleiding</title>
<author title="Author"><mail link="drobbins@gentoo.org">Daniel Robbins</mail></author>
<author title="Author"><mail link="zhen@gentoo.org">John P. Davis</mail></author>
<author title="Editor"><mail link="peesh@gentoo.org">Jorge Paulo</mail></author>
<author title="Translator"><mail link="swift@gentoo.org">Sven Vermeulen</mail></author>
<license/>
<abstract>
Deze handleiding toont je hoe je webdocumentatie maakt door middel van de
nieuwe, eenvoudige Gentoo handleiding XML syntax. Deze syntax is het officiele
formaat voor de Gentoo Linux documentatie; ook dit document is met deze
XML-stijl geschreven. Deze handleiding vereist een basis werkkennis van XML en
HTML.
</abstract>
<version>2.0</version>
<date>13 Mei 2003</date>
<chapter>
<title>Handleiding Basiszaken</title>
<section>
<title>Doeleinden Handleiding XML</title>
<body>
<p>
De XML syntax voor de handleidingen is eenvoudig maar krachtig, zodat het
eenvoudig is om te leren alsook voldoende mogelijkheden biedt om
webdocumentatie te schrijven. Het aantal tags is op een minimum behouden --
enkel deze die we nodig hebben. Dit maakt het eenvoudig om de handleiding in
andere formaten te verkrijgen, zoals DocBook XML/SGML of webklare HTML.
</p>
<p>
Het doel is om het eenvoudig te maken om XML handleidingdocumenten te
<e>maken</e> en <e>transformeren</e>.
</p>
</body>
</section>
<section>
<title>XML handleiding syntaxis omvormen naar HTML</title>
<body>
<p>
Alvorens we een kijkje nemen naar de handleiding syntax zelf is het handig te
weten hoe we deze XML transformeren in webklare HTML. Om dit te doen maken we
gebruik van een speciaal bestand genaamd <path>guide.xsl</path>, samen met een
commandline XSLT verwerkingstooltje (ook "engine" geheten). Het
<path>guide.xsl</path> bestand beschrijft hoe we de inhoud van een XML
broncodebestand moeten omvormen naar HTML. De tool die we hiervoor gebruiken is
<c>xsltproc</c>, welke in het <i>libxslt</i> pakket zit.
</p>
<pre caption="libxslt installeren">
# <i>emerge libxslt</i>
</pre>
<p>
Nu dat we weten hoe we het converteren, moeten we nog weten hoe we het
schrijven. In andere woorden: we hebben Gentoo XML documenten nodig om om te
vormen. Gentoo heeft 2 types van tarballs beschikbaar om te downloaden:
</p>
<p>
<b>Het eerste type bevat de volledige up-to-date Gentoo Linux website</b>.
Hierin zitten onze XSL templates, dus indien je van plan bent om een document
om te vormen, dan heb je deze tarball nodig. Je kan deze <uri
link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz">hier</uri>
vinden.
</p>
<p>
<b>Het tweede type bevat een dagelijkse snapshot van onze XML documentatie
broncodebestanden</b> in elke taal die we aanbieden. Weet wel dat het
onmogelijk is om met deze tarball de documentatie om te vormen naar HTML, dus
gelieve de web tarball te downloaden indien je je eigen documentatie wil
ontwikkelen. Deze tarballs zijn vooral interessant voor de vertalers. Je kan ze
<uri link="http://www.gentoo.org/dyn/doc-snapshots">hier</uri> vinden.
</p>
<p>
Nadat de web tarball gedownload en uitgepakt is ga je naar de directorie waarin
de tarball zijn bestanden geplaatst heeft, en daarin ga je in de
<path>htdocs</path> directorie. Browse wat rond en zorg ervoor dat je je goed
voelt met de layout, en bemerk de <path>xsl</path> en <path>doc</path>
directories. Zoals je waarschijnlijk wel kan raden zitten de XSL stylebestanden
in <path>xsl</path> en de documentatie in <path>doc</path>. Voor testdoeleinden
gaan we nu de Gentoo Linux CD Installatiegids, te vinden in
<path>doc/nl/gentoo-x86-install.xml</path> nemen. Nu dat de locaties van de XSL
en XML bestanden bekend zijn gaan we de documenten transformeren met
<c>xsltproc</c>.
</p>
<pre caption="gentoo-x86-install.xml transformeren">
# <i>xsltproc xsl/guide.xsl doc/nl/gentoo-x86-install.xml > /tmp/install.html</i>
</pre>
<p>
Indien alles goed verliep zal je nu een webklare versie van
<path>gentoo-x86-install.xml</path> in <path>/tmp/install.html</path> staan
hebben. Om dit document goed weer te geven in een webbrowser moet je nog enkele
bestanden van <path>htdocs</path> overkopieren naar <path>/tmp</path>, zoals
<path>css/main.css</path> en (om veilig te spelen) de ganse <path>images</path>
directorie.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Handleiding XML</title>
<section>
<title>Basisstructuur</title>
<body>
<p>
Nu dat je weet hoe je handleiding-XML omvormt ben je klaar om de
handleiding-XML syntax te leren. We starten met de initiele tags die gebruikt
worden in een XML document:
</p>
<pre caption="Het initiele gedeelte van een XML document">
<?xml version='1.0' encoding="UTF-8"?>
<guide link="relatieve_link_naar_je_handleiding">
<title><i>Gentoo Linux Documentatie Handleiding</i></title>
<author title="<i>Chief Architect</i>"><mail link="<i>drobbins@gentoo.org</i>">
<i>Daniel Robbins</i></mail>
</author>
<author title="<i>Editor</i>"><mail link="<i>thomasfl@gentoo.org</i>">
<i>Thomas Flavel</i></mail>
</author>
<abstract><i>Deze handleiding toont je hoe webdocumentatie maakt met de
nieuwe Gentoo handleiding syntax. Deze syntax is het officiele formaat voor de
Gentoo Linux webdocumentatie, en dit document werd dan ook gemaakt in dat
formaat.</i> </abstract>
<version><i>1.0</i></version>
<date><i>29 Mar 2001</i></date>
</pre>
<p>
Op de eerste regel zien we een vereiste tag die het document identificeert als
een XML document. Daarop volgend komt de <c><guide></c> tag -- het
volledige document moet tussen <c><guide> ... </guide></c>
gedefinieerd zijn. Daarop volgt een <c><title></c> tag, die gebruikt
wordt om de titel van het volledige document te definieren.
</p>
<p>
Daarna komen we aan de <c><author></c> tags, welke informatie bevatten
van de verschillende auteurs van het document. Elke <c><author></c> tag
staat een optioneel <c>title=</c> element toe waarmee je de auteur's relatie
met het document kan omschrijven (auteur, co-auteur, editor, vertaler, ...). In
dit specifiek geval worden de namen van de auteurs tussen nog andere tags
gedefinieerd, namelijk de <c><mail></c> tags, die gebruikt worden om een
e-mailadres te definieren voor deze specifieke persoon. Deze
<c><mail></c> tag is optioneel en mag weggelaten worden, en er worden
niet meer dan 1 <c><author></c> elementen vereist per document.
</p>
<p>
Hierna komen we bij het <c><abstract></c>, <c><version></c> en
<c><date></c> gedeelte, welke gebruikt worden om een samenvatting van het
document, de huidige versie respectievelijk de datum (in DD MMM YYYY formaat)
te definieren. Dit rond onze inleiding tot de begintags af die elk document
moet bevatten. Behalve de <c><title></c> en <c><mail></c> tags
moeten deze tags nergens anders voorkomen behalve na de <c><guide></c>
tag, waarbij we voor de eenvoud vragen deze in het begin van het document te
definieren.
</p>
</body>
</section>
<section>
<title>Hoofdstukken en secties</title>
<body>
<p>
Nu dat de initiele tags uitgelegd zijn ben je klaar om structurele tags aan je
document toe te voegen. Handleidingdocumenten zijn ingedeeld in hoofdstukken,
die op zich een of meerdere secties bevat. Elk hoofdstuk en sectie bevat een
titel. Hieronder vind je een voorbeeld hoofdstuk met een enkelvoudige sectie,
die op zich een paragraaf bevat. Indien je deze XML aan de <uri
link="#doc_chap2_pre1">vorige XML-tekst</uri> toevoegt en je de tekst afsluit
met een <c></guide></c> dan zal een een geldig, minimaal
handleidingdocument hebben:
</p>
<pre>
<chapter>
<title><i>Dit is mijn hoofdstuk</i></title>
<section>
<title><i>Dit is sectie 1 van mijn hoofdstuk</i></title>
<body>
<p><i>Dit is de eigenlijke tekst van mijn sectie</i></p>
</body>
</section>
</chapter>
</pre>
<p>
Hierboven hebben we de titel van het hoofdstuk ingesteld door
<c><title></c> te gebruiken binnenin het <c><chapter></c> element.
Daarna hebben we een sectie aangemaakt met het <c><section></c> element.
Indien je hierin kijkt zie je dat er 2 elementen in zitten:
<c><title></c> en <c><body></c>. Het <c><title></c> element
kennen we al, maar <c><body></c> nog niet -- deze bevat de werkelijke
inhoud van een sectie. We zullen later kijken naar welke elementen je in een
<c><body></c> kan plaatsen.
</p>
<note>
Een <c><guide></c> element kan verschillende <c><chapter></c>
elementen bevatten, en elke <c><chapter></c> kan verschillende
<c><section></c> elementen bevatten. Een <c><section></c> element
mag echter maar 1 <c><body></c> bevatten.
</note>
</body>
</section>
<section>
<title>Een voorbeeld <body></title>
<body>
<p>
Het is nu tijd om de werkelijke inhoud van het document neer te pennen.
Hieronder vind je wat voorbeeld XML-code om in <c><body></c> te
gebruiken.
</p>
<pre>
<p>
Dit is een paragraaf. <path>/etc/passwd</path> is een bestand.
<uri>http://www.gentoo.org</uri> is de beste website die er
bestaat. Type <c>ls</c> als je dat wil. Ik moet nu <e>werkelijk</e> gaan slapen.
</p>
<pre>
Dit is tekst of commando-uitvoer.
# <i>dit is gebruikers invoer</i>
Maak HTML/XML eenvoudiger om te lezen door nadrukken te leggen:
<foo><i>bar</i></foo>
<codenote>Dit is hoe je commentaar in een code blok steekt</codenote>
</pre>
<note>Dit is een nota.</note>
<warn>Dit is een waarschuwing.</warn>
<impo>Dit is belangrijk.</impo>
</pre>
<p>
Hieronder vind je hoe deze getoond wordt:
</p>
<p>
Dit is een paragraaf. <path>/etc/passwd</path> is een bestand.
<uri>http://www.gentoo.org</uri> is de beste website die er bestaat.
Type <c>ls</c> als je dat graag doet. Ik moet nu <e>werkelijk</e> gaan slapen.
</p>
<pre>
Dit is tekst of commando-uitvoer.
# <i>dit is gebruikers invoer</i>
Maak HTML/XML eenvoudiger om te lezen door nadrukken te leggen:
<foo><i>bar</i></foo>
<codenote>Dit is hoe je commentaar in een code blok steekt</codenote>
</pre>
<note>Dit is een nota.</note>
<warn>Dit is een waarschuwing.</warn>
<impo>Dit is belangrijk.</impo>
</body>
</section>
<section>
<title>De <body> tags</title>
<body>
<p>
We hebben een heleboel elementen in de voorgaande sectie geintroduceerd. Hier
leggen we uit wat je ervan moet weten. De <c><p></c> (paragraaf),
<c><pre></c> (code blok), <c><note></c>, <c><warn></c>
(waarschuwing) en <c><impo></c> (belangrijk) elementen kunnen allemaal
een of meerdere regels tekst bevatten. Behalve het <c><table></c> element
(die we later zullen bespreken) zijn dit de enigste elementen die in een
<c><body></c> mogen voorkomen. Verder mogen deze elementen niet gestapeld
worden -- met andere woorden, je mag bv geen <c><note></c> element in een
<c><p></c> element steken. Zoals je wel kan raden behoudt het
<c><pre></c> element de witruimte perfect, wat het zeer interessant maakt
voor code en uitvoer. Je dan de <c><pre></c> ook een naam geven:
</p>
<pre caption = "<pre> benaming">
<pre caption = "Uitvoer van uptime"<
# <i>uptime</i>
16:50:47 up 164 days, 2:06, 5 users, load average: 0.23, 0.20, 0.25
</pre>
</pre>
</body>
</section>
<section>
<title><path>, <c> en <e></title>
<body>
<p>
De <c><path></c>, <c><c></c> en <c><e></c> elementen kunnen
binnenin elk mogelijk <c><body></c> kind gebruikt worden, behalve in
<c><pre></c>.
</p>
<p>
Het <c><path></c> element wordt gebruikt om referenties naar
<e>bestanden op het systeem</e> -- ofwel een <e>absoluut of relatief</e> pad,
of een <e>gewoon bestandsnaam</e>. Dit element wordt meestal met een monospaced
font getoond om ze te onderscheiden van het standaard paragraaf type.
</p>
<p>
Het <c><c></c> element wordt gebruikt om een <e>commando</e> of
<e>gebruikers invoer</e> aan te geven. Beschouw <c><c></c> als een manier
om de gebruiker te waarschuwen dat hetgeen wat ze intypen een actie als gevolg
heeft. Bijvoorbeeld zijn alle elementen in dit document tussen <c><c></c>
geplaatst omdat ze iets representeren dat de gebruiker moet invoeren en dat
geen pad is. Door de <c><c></c> elementen te gebruiken help je je lezers
om snel de commando's te identificeren die ze moeten ingeven. Omdat
<c><c></c> elementen visueel al volledig anders worden getoond dan de
gewone tekst <e>is het meestal niet nodig deze tussen quotes te plaatsen</e>.
Je moet dus geen "<c><c></c>" tussen accenten plaatsen zoals nu net
gebeurde. Door het ontwijken van teveel quotes maak je het document meer
leesbaar.
</p>
<p>
<c><e></c> wordt gebruikt om nadruk te leggen op een woord of zin;
bijvoorbeeld: Ik moet <e>werkelijk</e> meer gebruik maken van puntkomma's.
Zoals je kan zien is deze tekst anders dan de rest van de zin. Dit geeft het
woord/zin tussen deze elementen meer kracht.
</p>
</body>
</section>
<section>
<title><mail> en <uri></title>
<body>
<p>
We hebben eerder al <c><mail></c> gezien; ze wordt gebruikt om een
gedeelte van de tekst te linken met een e-mailadres; je definieert ze door
<c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>.
</p>
<p>
Het <c><uri></c> element wordt gebruikt om naar internetlocaties te
wijzen. Je kan ze in 2 vormen gebruiken: de eerste wanneer je de werkelijke url
ook in je tekst wil, zoals de link naar <uri>http://www.gentoo.org</uri>.
Hiervoor zet je <c><uri>http://www.gentoo.org</uri></c>. De andere
vorm is wanneer je een url aan een deel van de tekst wil linken, zoals in <uri
link="http://www.gentoo.org">de Gentoo Linux website</uri>. Om <e>deze</e> link
te maken zet je <c><uri link="http://www.gentoo.org">de Gentoo Linux
website</uri></c>.
</p>
</body>
</section>
<section>
<title>Figuren</title>
<body>
<p>
Hier vind je hoe je figuren in je document voegt -- <c><figure
link="mijnfiguur.png" short="mijn figuur" caption="dit is mijn favoriete
figuur"/></c>. Het <c>link=</c> attribuut wijst naar de afbeelding, het
<c>short=</c> attribuut naar een kleine uitleg (op dit moment wordt dat
gebruikt om de HTML <c>alt=</c> van <c><img></c> in te vullen) en een
bijhorende tekst. Dit is dus niet echt moeilijk, niet? We laten tevens de
standaard HTML-stijl <img src="foo.gif"/> toe om afbeeldingen zonder
bijhorende tekst, randen e.d. in te voegen.
</p>
</body>
</section>
<section>
<title>Tabellen en lijsten</title>
<body>
<p>
Handleidingen ondersteunen een eenvoudige tabel-syntax gelijkaardig aan die van
HTML. Om een tabel te starten gebruik je een <c><table></c> element. Je
start een regel met het <c><tr></c> element. Indien je echter tabeldata
wil invoegen gebruiken we <e>niet</e> het <td> element, maar
<c><th></c> indien je een hoofding toevoegt en <c><ti></c> indien
je normale data toevoegt. Je kan <c><th></c> overal gebruiken waar je een
<c><ti></c> kan gebruiken -- er is geen verplichting om <c><th></c>
enkel in de eerste regel te gebruiken. Ook laten deze elementen geen extra tags
toe, maar in de toekomst zullen er enkele mogelijk gemaakt worden (zoals het
<c>caption=</c> attribuut voor <c><table></c>).
</p>
<p>
Om een geordende of ongeordende lijst te maken gebruik je de HTML-elementen
<c><ol></c>, <c><ul></c> en <c><li></c>. Dergelijke lijsts
mogen enkel binnenin een <c><p></c>, <c><ti></c>,
<c><note></c>, <c><warn></c> of <c><impo></c> element
voorkomen.
</p>
</body>
</section>
<section>
<title>Intra-document referenties</title>
<body>
<p>
De handleiding-stijl maakt het zeer eenvoudig referenties te maken naar andere
delen in het document via hyperlinks. Je kan een link naar <uri
link="#doc_chap1">Hoofdstuk 1</uri> maken met <c><uri
link="#doc_chap1">Hoofdstuk 1</uri></c>. Om naar <uri
link="#doc_chap1_sect2">sectie 2 van hoofdstuk 1</uri> te wijzen type je
<c><uri link="#doc_chap1_sect2>sectie 2 van hoofdstuk 1</uri></c>.
Om naar figuur 3 in hoofdstuk 1 te wijzen, type je <c><uri
link="#doc_chap1_fig3">figuur 1.3</uri></c>. Of je verwijst naar <uri
link="#doc_chap2_pre2">code listing 2 in hoofdstuk 2</uri> met <c><uri
link="#doc_chap2_pre2">code listing 2 in hoofdstuk 2</uri></c>. We
gaan later nog andere auto-link mogelijkheden (zoals tabellen) toevoegen.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Referenties</title>
<section>
<title>Start uw creativiteit</title>
<body>
<p>
De handleiding syntax is gemaakt om "eenvoudig en snel" te zijn zodat
ontwikkelaars meer tijd kunnen spenderen aan het schrijven van de
documentatie dan het leren van de XML syntax. Hopelijk zal dit de
ontwikkelaars die niet gemakkelijk documentatie schrijven overtuigen om
goede kwaliteitsdocumenten neer te poten. Indien je graag helpt in het
ontwikkelen van documentatie, mail dan naar <mail
link="gentoo-doc@gentoo.org">gentoo-doc mailinglist</mail> waarin je dan
vermeldt wat je wil schrijven. Veel plezier!
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb