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
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
|
<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/de/xml-guide.xml,v 1.7 2003/12/14 21:10:17 dertobi123 Exp $ -->
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<!-- English CVS Version: 1.24 -->
<guide link="/doc/de/xml-guide.xml">
<title>Gentoo Linux Dokumentationsleitfaden</title>
<author title="Editor">
<mail link="drobbins@gentoo.org">Daniel Robbins</mail>
</author>
<author title="Author"><!-- zhen@gentoo.org -->John P. Davis
</author>
<author title="Editor">
<mail link="peesh@gentoo.org">Jorge Paulo</mail>
</author>
<author title="Übersetzung">
<mail link="kontakt@hendrik-brandt.de">Hendrik Brandt</mail>
</author>
<author title="Übersetzung">
<mail link="dertobi123@gentoo.org">Tobias Scherbaum</mail>
</author>
<abstract>
Dieser Leitfaden erklärt Ihnen, wie Sie Dokumente mit Hilfe der neuen
minimalitischen Gentoo GuideXML Syntax erstellen können.
Diese Syntax stellt das offizielle Format für Gentoo-Linux-Dokumente dar -
auch dieses Dokument wurde mit Hilfe der Gentoo's Guide-XML erstellt.
Dieser Leitfaden setzt Grundkenntnisse in XML und HTML voraus.
</abstract>
<version>2.6</version>
<date>12. Dezember 2003</date>
<chapter>
<title>Grundlagen</title>
<section>
<title>Ziele des Gentoo-Guide-XML-Designs</title>
<body>
<p>
Die Guide-XML-Syntax ist zugleich minimalistisch als auch ausdrucksstark,
so dass sie schnell erlernbar ist, gleichzeitg aber alle notwendigen
Eigenschaften bereitstellt, die wir für das Erstellen von Internet-Dokumenten
brauchen. Die Anzahl der Tags ist auf ein Minimum beschränkt -- nur die die
wir brauchen. Dadurch wird es einfacher Dokumente in andere Formate,
wie z.B. DocBook, XML/SGML oder HTML umzuwandeln.
</p>
<p>
Das Ziel ist, dass <e>Erstellen</e> und <e>Umwandeln</e> von GuideXML
Dokumenten zu vereinfachen.
</p>
</body>
</section>
<section>
<title>
Weitere Quellen
</title>
<body>
<p>
Wenn Sie planen Dokumentation zu Gentoo beizutragen oder GuideXML testen wollen,
lesen Sie bitte die <uri link="http://www.gentoo.org/proj/en/gdp/tipsntricks.xml">
Tipps und Tricks</uri>, welche Tipps und Tricks zur Erstellung
von Dokumentation beinhalten.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Guide-XML</title>
<section>
<title>Grundstruktur</title>
<body>
<p>
Jetzt, da Sie wissen, wie man Guide-XML umwandelt, sind Sie so weit, um die
GuideXML Syntax zu erlernen. Wir beginnen mit den einleitenden Tags, die in
einem Guide-XML-Dokument verwendet werden:
</p>
<pre caption="Der einleitende Teil eines Guide-XML-Dokuments">
<?xml version='1.0' enconding="UTF-8"?>
<guide link="Relativer Link zu Ihrem Guide">
<title><i>Gentoo Linux Dokumentationsleitfaden</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>
<author title="<i>Übersetzung</i>">
<mail link="<i>kontakt@hendrik-brandt.de</i>"><i>Hendrik Brandt</i></mail>
</author>
<abstract><i>
Dieser Leitfaden erklärt Ihnen, wie Sie Dokumente mit Hilfe der neuen
minimalitischen Gentoo GuideXML Syntax erstellen können.
Diese Syntax stellt das offizielle Format für Gentoo-Linux-Dokumente dar -
auch dieses Dokument wurde mit Hilfe der Gentoo's Guide-XML erstellt.
Dieser Leitfaden setzt Grundkenntnisse in XML und HTML voraus.</i>
</abstract>
<license/>
<version><i>1.0</i></version>
<date><i>29. März 2001</i></date>
</pre>
<p>
In der ersten Zeile sehen wir den notwendigen Tag der festlegt, dass das
Dokument in XML beschrieben ist. Darauf folgt der Tag <c><guide></c>
-- das gesamte Dokument ist von einem <c><guide> </guide></c>
-Paar umschlossen. Schließlich gibt es noch den Tag <c><title></c>,
mit dem der Titel für das Dokument festgelegt wird.
</p>
<p>
Als nächstes kommen wir zu den <c><author></c>-Tags, welche
Informationen über die unterschiedlichen Autoren eines Dokumentes enthalten.
Jeder <c><author></c>-Tag besitzt ein optionales Element <c>title=</c>.
Dieses wird benutzt, um die Beziehungen der Autoren zum Dokument (Autor,
Co-Autor, Bearbeiter, Übersetzer usw.) zu beschreiben. Im vorliegenden
Beispiel sind die Namen der Autoren in einem weiteren Tag eingeschlossen --
dem Tag <c><mail></c>. Mit diesem kann eine Email-Adresse mit der
betreffenden Person verbunden werden. Der Tag <c><mail></c> ist
optional und kann weggelassen werden. Weiterhin wird nicht mehr als ein
Element <c><author></c> pro Dokument benötigt.
</p>
<p>
Es folgen die Tags <c><abstract></c>, <c><version></c> und
<c><date></c>, die benutzt werden, um die Überschrift, die
gegenwärtige Versionsnummer und das gegenwärtige Versionsdatum
(im Format TT MMM JJJJ) des Dokuments festzulegen. Damit sind alle Tags,
die zu Beginn des Dokuments stehen sollten genannt. Ebenso wie die Tags
<c><title></c> und <c><mail></c>, sollten diese nur direkt im
Tag <c><guide></c> und nicht irgendwo anders stehen. Weiterhin wird
empfohlen (aber nicht gefordert), dass diese Tags vor dem eigentlichen
Inhalt im Dokument stehen.
</p>
<p>
Und schliesslich haben wir das <c><license/></c> Tag, mit dem wir das
Dokument unter der <uri
link="http://creativecommons.org/licenses/by-sa/1.0/">Creative
Commons - Attribution / Share Alike</uri> Lizenz veröffentlichen, wie
es die <uri
link="http://www.gentoo.org/doc/en/doc-policy.xml">Dokumentations Richtlinie
</uri> erfordert.
</p>
</body>
</section>
<section>
<title>Kapitel und Abschnitte</title>
<body>
<p>
Sobald Sie die einleitenden Tags spezifiziert haben, können Sie damit
beginnen, Strukturelemente des Dokuments hinzuzufügen. Guide-Dokumente
sind unterteilt in Kapitel (chapter) und jedes Kapitel kann ein oder
mehr Abschnitte (section) enthalten. Jedes Kapitel und jeder Abschnitt hat
eine Überschrift. Hier ist ein Beispielkapitel mit einem Abschnitt,
der einen Absatz enthält. Wenn Sie dieses XML an das XML im
<uri link="#doc_pre2_pre1">vorherigen Auszug</uri> anhängen und ein
<c></guide></c> am Ende hinzufügen, haben Sie ein (minimales)
Guide-Dokument:
</p>
<pre>
<chapter>
<title><i>Das ist mein Kapitel</i></title>
<section>
<title><i>Hier ist Abschnitt eins in meinem Kapitel</i></title>
<body>
<p>
<i>Dies ist der eigentliche Textinhalt meines Abschnitts.</i>
</p>
</body>
</section>
</chapter>
</pre>
<p>
Wie Sie sehen haben ich dem Kapitel durch das hinzufügen eines Kindelements
<c><title></c> in das Element <c><chapter></c> eine Überschrift
gegeben. Anschliessend habe ich einen Abschnitt durch das hinzufügen des
Elements <c><section></c> erzeugt. Wenn Sie sich das Element
<c><section></c> anschauen, werden Sie zwei Kindelemente erkennen --
ein <c><title></c> und ein <c><body></c> Element. Da Ihnen das
Element <c><title></c> bereits bekannt ist, sei hier das Element
<c><body></c> erläutert; dieses enthält den eigenlichen Inhalt des
derzeitigen Abschnitts. Wir betrachten nun kurz die Tags die innerhalb von
<c><body></c> erlaubt sind.
</p>
<note>
Das Element <c><guide></c> kann mehrere Elemente
<c><chapter></c>, und das Element <c><chapter></c>
kann mehrere Elemente <c><section></c> enthalten. Allerdings kann das
Element <c><section></c> nur einmal das Element <c><body></c>
enthalten.
</note>
</body>
</section>
<section>
<title>Ein Beispiel zu <body></title>
<body>
<p>
Jetzt ist es an der Zeit zu lernen, wie man den eigentlichen Inhalt auszeichnet.
Hier ist der XML-Code zu einem Beispiel-<c><body></c>-Element:
</p>
<pre>
<p>
Das ist ein Absatz. <path>/etc/passwd</path> ist eine Datei.
<uri>http://www.gentoo.de</uri> ist meine Lieblings-Web-Seite.
Geben Sie <c>ls</c> ein - wenn sie wollen. Ich sollte jetzt <e>wirklich</e> schlafen gehen.
</p>
<pre>
Das ist Textausgabe oder Quelltext.
# <i>das sind Benutzereingaben</i>
Um HTML/XML lesbarer zu machen, sollten Sie verschiedene Hervorhebungen verwenden:
<foo><i>bla</i></foo>
<codenote>So wird eine Notiz in einen Quelltextabschnitt eingefügt</codenote>
</pre>
<note>
Das ist eine Anmerkung.
</note>
<warn>
Das ist eine Warnung.
</warn>
<impo>
Das ist wichtig.
</impo>
</pre>
<p>
Und so wird dieses <c><body></c>-Element dargestellt:
</p>
<p>
Das ist ein Absatz. <path>/etc/passwd</path> ist eine Datei.
<uri>http://www.gentoo.de</uri> ist meine Lieblings-Web-Seite.
Geben Sie <c>ls</c> ein - wenn Sie wollen. Ich sollte jetzt
<e>wirklich</e> schlafen gehen.
</p>
<pre>
Das ist Textausgabe oder Quelltext.
# <i>das sind Benutzereingaben</i>
Um HTML/XML lesbacher zu machen, sollten Sie verschiedene Hervorhebungen verwenden:
<foo><i>bla</i></foo>
<codenote>So wird eine Notiz in einen Quelltextabschnitt eingefügt</codenote>
</pre>
<note>
Das ist eine Anmerkung.
</note>
<warn>
Das ist eine Warnung.
</warn>
<impo>
Das ist wichtig.
</impo>
</body>
</section>
<section>
<title>Die Tags <body></title>
<body>
<p>
Im vorherigen Abschnitt wurde eine Menge neuer Tags eingeführt -- jetzt werden
sie erläutert. Die Tags <c><p></c> (Absatz), <c><pre></c>
(Quelltextabschnitt), <c><note></c> (Anmerkung), <c><warn></c>
(Warnung) und <c><impo></c> (Wichtig), können alle ein oder mehrere
Zeilen Text enthalten. Neben dem Element <c><table></c> (auf das wir
später eingehen), sollten das die einzigen ags, die innerhalb des Elements
<c><body></c> stehen, sein. Weiterhin sollten diese Tags <e>nie</e>
verschachtelt werden -- mit anderen Worten, Sie sollten das Element
<c><note></c> nicht innerhalb des Elements <c><p></c> verwenden!
Wie Sie vielleicht bemerken, gibt das Element <c><pre></c> Leerzeichen
und Zeilenumbrüche exakt wieder - dadurch empfiehlt es sich für
Quelltextschnipzel.
Sie können auch das <c><pre></c> Tag benutzen:
</p>
<pre caption = "<pre>">
<pre caption = "Ausgabe von 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> und <e></title>
<body>
<p>
Die Elemente <c><path></c>, <c><c></c> und <c><e></c>
können innerhalb jedes <c><body></c>-Kindelements verwendet werden,
ausgenommen ist <c><pre></c>.
</p>
<p>
Das Element <c><path></c> wird verwendet um Text hervorzuheben, der auf
eine <e>Datei auf der Festplatte</e> verweist -- genauso wie für einen
<e>absoluten oder realtiven Pfad</e> oder einfach einen
<e>Dateinamen</e>. Dieses Element wird normalerweise mit einer
Maschinentextschrift dargestellt, um es vom Rest des Textes abzugrenzen.
</p>
<p>
Das Element <c><c></c> wird verwendet, um <e>Befehle</e> oder
<e>Benutzereingaben</e> zu markieren. Sie sollten sich <c><c></c>
als eine Möglichkeit vorstellen, dem Leser mitzuteilen, dass er etwas eingeben
kann, was zu irgendeiner Aktion führt. Zum Beispiel sind alle XML-Tags
in diesem Dokument von <c><c></c> umschlossen, um zu zeigen, dass der
Benutzer etwas anderes als einen Pfad eingeben kann. Indem Sie das Element
<c><c></c> verwenden, erleichtern Sie es Ihren Lesern, Befehle die sie
eingeben müssen schneller zu erkennen. Desweiteren ist es auf Grund dessen,
dass <c><c></c>-Elemente sich vom regulären Text abheben, <e>nicht
zwingend notwendig, Benutzereingaben mit doppelten Anführungszeichen zu
umgeben</e>. Verwenden Sie zum Beispiel das Element "<c><c></c>" nicht
wie in diesem Satz. Vermeiden Sie die Benutzung von nicht-notwendigen
doppelten Anführungszeichen, um das Dokument leserlicher und ansprechender
zu gestalten.
</p>
<p>
<c><e></c> wird benutzt, um Wörter oder Wortgruppen zu betonen;
zum Beispiel: Ich sollte <e>wirklich</e> öfters Semikola verwenden. Wie Sie
sehen können, hebt sich dieser Text zur Betonung von der normalen Absatzschrift
ab. Dadurch wird das von ihnen Gesagte <e>schlagkräftiger</e>!
</p>
</body>
</section>
<section>
<title><mail> und <uri></title>
<body>
<p>
Wir hatten uns den Tag <c><mail></c> schon vorhin angesehen; er wird
benutzt, um einen Text mit einer speziellen Email-Adresse zu verbinden; er
hat die Form <c><mail link="mm@bla.de">Herr Martin Mustermann
</mail></c>.
</p>
<p>
Der Tag <c><uri></c> wird verwendet, um auf Dateien oder Seiten im
Internet zu verweisen. Es gibt zwei Varianten. Bei der ersten wird die URI
direkt im Text angezeigt, so wie dieser Link zu <uri>http://www.gentoo.de</uri>.
Um diesen Link zu erzeugen, habe ich <c><uri>http://www.gentoo.de
</uri></c> eingegeben. Die Alternative wird verwendet, wen Sie eine URI
mit einem abweichenden Text verknüpfen wollen -- z.B.
<uri link="http://www.gentoo.de">das deutschsprachige Gentoo Linux Portal</uri>.
Um <e>diesen</e> Link zu erzeugen, wurde
<c><uri link="http://www.gentoo.de">das deutschsprachige Gentoo Linux Portal
</uri></c> eingegeben.
</p>
</body>
</section>
<section>
<title>Grafiken</title>
<body>
<p>
Und so können Sie Grafiken in ein Dokument einfügen: <c><figure
link="meinbild.png" short="mein Bild" caption="für immer mein Lieblingsbild"/
></c>. Das Attribut <c>link=</c> verweist auf die gewünschte Grafikdatei,
das Attribut <c>short=</c> legt eine Kurzbeschreibung fest (wird derzeit für
das Attribute <c>alt= </c> im HTML-Tag <c><img></c> verwendet) und mit
<c>caption= </c> wird schließlich eine Bildunterschrift festgelegt -- alles in
allem nicht allzu schwer :) Ausserdem wird noch der Tag
<img src="bla.gif"/> aus HTML unterstützt, um Grafiken ohne Unterschrift,
Ränder u.a. einzufügen.
</p>
</body>
</section>
<section>
<title>Tabellen und Listen</title>
<body>
<p>
Guide stellt eine vereinfachte Tabellensyntax, vergleichbar mit der von HTML,
bereit. Um eine Tabelle zu erzeugen, benutzen Sie den Tag <c><table></c>.
Eine Reihe wird mit <c><tr></c> begonnen. Allerdings unterstützt GuideXML
<e>keinen</e> Tag <td> wie in HTML, um die eigentlichen Tabelleninhalte
einzufügen; verwenden Sie stattdessen <c><th></c> für den Tabellenkopf
und <c><ti></c> wenn Sie normale Informationen einfügen wollen. Sie
können <c><th></c> überall da verwenden, wo Sie auch
<c><ti></c> verwenden können -- es gibt also keinen Zwang
<c><th></c>-Elemente nur in der ersten Reihe zu verwenden. Derzeit
stellen diese Tags noch keine Attribute bereit, allerdings werden bald welche
hinzugefügt (wie z.B. ein Attribut <c>caption=</c> für <c><table></c>).
</p>
<p>
Um eine sortierte oder unsortierte Liste zu erzeugen, verwenden Sie einfach
die gleichwertigen HTML-Tags <c><ol></c>, <c><ul></c> und
<c><li></c>. Listen-Tags sollten nur innerhalb von
<c><p></c>, <c><ti></c>, <c><note></c>, <c><warn></c>
und <c><impo></c> verwendet werden.
</p>
</body>
</section>
<section>
<title>Verweise innerhalb des Dokuments</title>
<body>
<p>
In Guide ist es wirklich einfach, Verweise zu anderen Teilen des Dokuments mit
Hilfe von Hyperlinks zu erstellen. Sie können einen Verweis zu
<uri link="#doc_chap1">Kapitel 1</uri> durch das Eingeben von
<c><uri link="#doc_chap1">Kapitel 1</uri></c> erzeugen. Um auf
<uri link="#doc_chap1_sect2">Abschnitt 2 in Kapitel 1</uri> zu verweisen,
geben Sie <c><uri link="#doc_chap1_sect2">Abschnitt 2 in Kapitel
1</uri></c> ein. Um auf Grafik 3 zu verweisen, geben Sie
<c><uri link="doc_chap1_fig3">Grafik 1.3</uri></c> ein;
oder für einen Verweis auf <uri link="#doc_chap2_pre2">Quelltextbeispiel 2.2</uri>
einfach <c><uri link="doc_chap2_pre2">Quelltextbeispiel 2.2</uri></c>.
In Zukunft werden weitere Möglichkeiten, der automatischen Verknüpfung
(wie z.B. Unterstützung von Tabellen) hinzukommen.
</p>
<p>
Allerdings ändern sich viele Anleitungen öfters und solches "Zählen" kann dann
zu fehlerhaften Links führen. Um dem abzuhelfen, kann ein Name für ein
<c><chapter></c> oder <c><section></c> mit Hilfe des <c>id</c>
Attributes hinzugefügt werden. Nun muss man nur noch auf dieses Attribut
verweisen:
</p>
<pre caption="Verwendung des id Attributes">
<chapter id="foo">
<title>Das ist foo!</title>
...
<p>
Weitere Informationen finden Sie im <uri link="#foo">foo Kapitel</uri>
</p>
</pre>
</body>
</section>
</chapter>
<chapter>
<title>Coding Style</title>
<section>
<title>Einleitung</title>
<body>
<p>
Da jede Gentoo Dokumentation eine große Anstregung ist und viele Leute
die Dokumentation ändern, ist ein Coding Style von Nöten.
Ein Coding Style beinhaltet zwei Teile. Der erste (Interner Coding Style)
erläutert wie die xml-Tags platziert werden sollen, der zweite beschreibt
den Inhalt; wie man die Leser nicht verwirrt.
</p>
<p>
Beide Teile werden jetzt erläutert.
</p>
</body>
</section>
<section>
<title>Interner Coding Style</title>
<body>
<p>
<b>Neue Zeilen</b> müssen direkt nach <e>jedem</e> GuideXML-Tag platziert werden
(öffnende und schliessende), ausgenommen für
<c><version></c>, <c><date></c>, <c><title></c>,
<c><th></c>, <c><ti></c>,
<c><li></c>, <c><i></c>, <c><e></c>,
<c><uri></c>, <c><path></c>, <c><b></c>,
<c><comment></c>, <c><codenote></c>, <c><mail></c>.
</p>
<p>
<b>Leere Zeilen</b> müssen direkt nach <e>jedem</e>
<c><body></c> (nur öffnende Tags) und vor <e>jedem</e>
<c><chapter></c>, <c><p></c>, <c><table></c>,
<c><author></c> (Gruppe), <c><pre></c>, <c><ul></c>,
<c><ol></c>, <c><warn></c>, <c><note></c> and
<c><impo></c> (nur öffnende Tags) platziert werden.
</p>
<p>
Ein <b>Zeilenumbruch</b> muss nach 80 Zeilen angewandt werden, ausser im
<c><pre></c> Tag. Nur wenn es keine andere Wahl gibt kann von dieser
Regel abgewichen werden (zum Beispiel wenn eine URL über das Maximum an Zeichen
hinausgeht). Der Editor muss dann beim nächsten Leerzeichen umbrechen.
</p>
<p>
<b>Einrücken</b> soll nich benutzt werden, ausser in XML Konstruktionen
bei denen die Parent Tags <c><tr></c> (von <c><table></c>),
<c><ul></c>, <c><ol></c> und <c><author></c> sind. Wenn
Einrücken benutzt wird, <e>müssen</e> zwei Leerzeichen für jede Einrückung
benutzt werden. Das heisst, <e>keine</e> Tabs und <e>nicht</e> mehr Leerzeichen.
</p>
<p>
Wenn ein Zeilenumbruch in eines der folgenden <c><ti></c>,
<c><th></c> oder <c><li></c> Konstrukte fällt, muss Einrückung
für den Inhalt benutzt werden.
</p>
<p>
Ein Beispiel für Einrückung ist:
</p>
<pre caption = "Beispiel: Einrückung">
<table>
<tr>
<th>Foo</th>
<th>Bar</th>
</tr>
<tr>
<ti>Das ist ein Beispiel für Einrückung.</ti>
<ti>
Wennn Text nicht in eine 80 Zeilen lange Zeile passt, müssen
Sie Einrückung benutzen, wenn das Parent Tag es erlaubt.
</ti>
</tr>
</table>
<ul>
<li>Erste Option</li>
<li>Zweite Option</li>
</ul>
</pre>
<p>
<b>Attribute</b> sollen keine Leerzeichen zwischen den Attributen haben.
"=" Ein Beispiel:
</p>
<pre caption="Attribute">
<comment>Falsch :</comment> <pre caption = "Attribute">
<comment>Richtig:</comment> <pre caption="Attribute">
</pre>
</body>
</section>
<section>
<title>Externer Coding Style</title>
<body>
<p>
Innerhalb von Tabellen (<c><table></c>) und Listings (<c><ul></c>
und <c><ol></c>), sollten Punkte (".") nur benutzt werden, wenn
mehrere Sätze benutzt werden. In diesem Fall sollte jeder Satz mit einem
Punkt enden.
</p>
<p>
Jeder Satz, auch innerhalb von Tabellen und Listings sollte mit einem
Großbuchstaben beginnen.
</p>
<pre caption="Punkte und Großbuchstaben">
<ul>
<li>Kein Punkt</li>
<li>Mit Punkt. Mehrere Sätze, Sie erinnern sich?</li>
</ul>
</pre>
<p>
Codelistings sollten <e>immer</e> eine <c>Beschreibung</c> haben.
</p>
<p>
Benutzen Sie soweit möglich <c><uri></c> mit dem <c>link</c> Attribut.
In anderen Worten, <uri link="http://www.gentoo.org">Gentoo
Website</uri> wird <uri>http://www.gentoo.org</uri> vorgezogen.
</p>
<p>
Wenn Sie etwas innerhalb eines <c><pre></c> Konstruktes kommentieren
möchten, benutzen Sie <c><codenote></c> wenn der Inhalt ein C or C++
Code Schnipsel ist. Andernfalls benutzen Sie <c><comment></c>.
Platzieren Sie den Kommentar <e>vor</e> dem Bezug des Kommentars.
</p>
<pre caption="Kommentar Beispiel">
<comment>(Ersetzen Sie "john" mit Ihrem Benutzer Namen)</comment>
# <i>id john</i>
</pre>
</body>
</section>
</chapter>
<chapter>
<title>Quellenangaben</title>
<section>
<title>Mit dem Schreiben beginnen</title>
<body>
<p>
Guide wurde speziell dafür entwickelt, es Entwicklern zu ermöglichen, mehr
Zeit mit dem Schreiben der Dokumentation und weniger mit dem Erlernen der
eigentlichen XML-Syntax zu verbringen. Wir hoffen, dass dies den Entwicklern
erlaubt, qualitativ hochwertige Gentoo-Linux-Dokumentation zu schreiben.
Wenn Sie uns helfen möchten (oder irgendeine Fragen zu GuideXML haben),
dann senden Sie eine Nachricht an die <mail link="gentoo-doc@gentoo.org">
gentoo-doc Mailing Liste</mail> (in Englisch!).
Wir wünschen viel Spass;!
</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb