Gentoo Logo

Disclaimer : Dit document is niet juist en is niet meer onderhouden.


Gentoo Linux XML Handleiding

Inhoud:

1.  Handleiding Basiszaken

Doeleinden Handleiding XML

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.

Het doel is om het eenvoudig te maken om XML handleidingdocumenten te maken en transformeren.

XML handleiding syntaxis omvormen naar HTML

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 guide.xsl, samen met een commandline XSLT verwerkingstooltje (ook "engine" geheten). Het guide.xsl bestand beschrijft hoe we de inhoud van een XML broncodebestand moeten omvormen naar HTML. De tool die we hiervoor gebruiken is xsltproc, welke in het libxslt pakket zit.

Codevoorbeeld 1.1: libxslt installeren

# emerge libxslt

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:

Het eerste type bevat de volledige up-to-date Gentoo Linux website. 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 hier vinden.

Het tweede type bevat een dagelijkse snapshot van onze XML documentatie broncodebestanden 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 hier vinden.

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 htdocs directorie. Browse wat rond en zorg ervoor dat je je goed voelt met de layout, en bemerk de xsl en doc directories. Zoals je waarschijnlijk wel kan raden zitten de XSL stylebestanden in xsl en de documentatie in doc. Voor testdoeleinden gaan we nu de Gentoo Linux CD Installatiegids, te vinden in doc/nl/gentoo-x86-install.xml nemen. Nu dat de locaties van de XSL en XML bestanden bekend zijn gaan we de documenten transformeren met xsltproc.

Codevoorbeeld 1.2: gentoo-x86-install.xml transformeren

# xsltproc xsl/guide.xsl doc/nl/gentoo-x86-install.xml > /tmp/install.html

Indien alles goed verliep zal je nu een webklare versie van gentoo-x86-install.xml in /tmp/install.html staan hebben. Om dit document goed weer te geven in een webbrowser moet je nog enkele bestanden van htdocs overkopieren naar /tmp, zoals css/main.css en (om veilig te spelen) de ganse images directorie.

2.  Handleiding XML

Basisstructuur

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:

Codevoorbeeld 2.1: Het initiele gedeelte van een XML document

<?xml version='1.0' encoding="UTF-8"?>
<guide link="relatieve_link_naar_je_handleiding">
<title>Gentoo Linux Documentatie Handleiding</title>
<author title="Chief Architect"><mail link="drobbins@gentoo.org">
	Daniel Robbins</mail>
</author>
<author title="Editor"><mail link="thomasfl@gentoo.org">
	Thomas Flavel</mail>
</author>

<abstract>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. </abstract>

<version>1.0</version>
<date>29 Mar 2001</date>

Op de eerste regel zien we een vereiste tag die het document identificeert als een XML document. Daarop volgend komt de <guide> tag -- het volledige document moet tussen <guide> ... </guide> gedefinieerd zijn. Daarop volgt een <title> tag, die gebruikt wordt om de titel van het volledige document te definieren.

Daarna komen we aan de <author> tags, welke informatie bevatten van de verschillende auteurs van het document. Elke <author> tag staat een optioneel title= 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 <mail> tags, die gebruikt worden om een e-mailadres te definieren voor deze specifieke persoon. Deze <mail> tag is optioneel en mag weggelaten worden, en er worden niet meer dan 1 <author> elementen vereist per document.

Hierna komen we bij het <abstract>, <version> en <date> 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 <title> en <mail> tags moeten deze tags nergens anders voorkomen behalve na de <guide> tag, waarbij we voor de eenvoud vragen deze in het begin van het document te definieren.

Hoofdstukken en secties

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 vorige XML-tekst toevoegt en je de tekst afsluit met een </guide> dan zal een een geldig, minimaal handleidingdocument hebben:

Codevoorbeeld 2.2:

<chapter>
<title>Dit is mijn hoofdstuk</title>
<section>
	<title>Dit is sectie 1 van mijn hoofdstuk</title>
	<body>
		<p>Dit is de eigenlijke tekst van mijn sectie</p>
	</body>
</section>
</chapter>

Hierboven hebben we de titel van het hoofdstuk ingesteld door <title> te gebruiken binnenin het <chapter> element. Daarna hebben we een sectie aangemaakt met het <section> element. Indien je hierin kijkt zie je dat er 2 elementen in zitten: <title> en <body>. Het <title> element kennen we al, maar <body> nog niet -- deze bevat de werkelijke inhoud van een sectie. We zullen later kijken naar welke elementen je in een <body> kan plaatsen.

Nota: Een <guide> element kan verschillende <chapter> elementen bevatten, en elke <chapter> kan verschillende <section> elementen bevatten. Een <section> element mag echter maar 1 <body> bevatten.

Een voorbeeld <body>

Het is nu tijd om de werkelijke inhoud van het document neer te pennen. Hieronder vind je wat voorbeeld XML-code om in <body> te gebruiken.

Codevoorbeeld 2.3:

<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>

<comment>// Dit is hoe je commentaar in een code blok steekt</comment>
</pre>
<note>Dit is een nota.</note>
<warn>Dit is een waarschuwing.</warn>
<impo>Dit is belangrijk.</impo>

Hieronder vind je hoe deze getoond wordt:

Dit is een paragraaf. /etc/passwd is een bestand. http://www.gentoo.org is de beste website die er bestaat. Type ls als je dat graag doet. Ik moet nu werkelijk gaan slapen.

Codevoorbeeld 2.4:

Dit is tekst of commando-uitvoer.
# dit is gebruikers invoer

Maak HTML/XML eenvoudiger om te lezen door nadrukken te leggen:
<foo>bar</foo>

Dit is hoe je commentaar in een code blok steekt

Nota: Dit is een nota.

Waarschuwing: Dit is een waarschuwing.

Belangrijk: Dit is belangrijk.

De <body> tags

We hebben een heleboel elementen in de voorgaande sectie geintroduceerd. Hier leggen we uit wat je ervan moet weten. De <p> (paragraaf), <pre> (code blok), <note>, <warn> (waarschuwing) en <impo> (belangrijk) elementen kunnen allemaal een of meerdere regels tekst bevatten. Behalve het <table> element (die we later zullen bespreken) zijn dit de enigste elementen die in een <body> mogen voorkomen. Verder mogen deze elementen niet gestapeld worden -- met andere woorden, je mag bv geen <note> element in een <p> element steken. Zoals je wel kan raden behoudt het <pre> element de witruimte perfect, wat het zeer interessant maakt voor code en uitvoer. Je dan de <pre> ook een naam geven:

Codevoorbeeld 2.5: <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>

<path>, <c> en <e>

De <path>, <c> en <e> elementen kunnen binnenin elk mogelijk <body> kind gebruikt worden, behalve in <pre>.

Het <path> element wordt gebruikt om referenties naar bestanden op het systeem -- ofwel een absoluut of relatief pad, of een gewoon bestandsnaam. Dit element wordt meestal met een monospaced font getoond om ze te onderscheiden van het standaard paragraaf type.

Het <c> element wordt gebruikt om een commando of gebruikers invoer aan te geven. Beschouw <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> geplaatst omdat ze iets representeren dat de gebruiker moet invoeren en dat geen pad is. Door de <c> elementen te gebruiken help je je lezers om snel de commando's te identificeren die ze moeten ingeven. Omdat <c> elementen visueel al volledig anders worden getoond dan de gewone tekst is het meestal niet nodig deze tussen quotes te plaatsen. Je moet dus geen "<c>" tussen accenten plaatsen zoals nu net gebeurde. Door het ontwijken van teveel quotes maak je het document meer leesbaar.

<e> wordt gebruikt om nadruk te leggen op een woord of zin; bijvoorbeeld: Ik moet werkelijk 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.

<mail> en <uri>

We hebben eerder al <mail> gezien; ze wordt gebruikt om een gedeelte van de tekst te linken met een e-mailadres; je definieert ze door <mail link="foo@bar.com">Mr. Foo Bar</mail>.

Het <uri> 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 http://www.gentoo.org. Hiervoor zet je <uri>http://www.gentoo.org</uri>. De andere vorm is wanneer je een url aan een deel van de tekst wil linken, zoals in de Gentoo Linux website. Om deze link te maken zet je <uri link="http://www.gentoo.org">de Gentoo Linux website</uri>.

Figuren

Hier vind je hoe je figuren in je document voegt -- <figure link="mijnfiguur.png" short="mijn figuur" caption="dit is mijn favoriete figuur"/>. Het link= attribuut wijst naar de afbeelding, het short= attribuut naar een kleine uitleg (op dit moment wordt dat gebruikt om de HTML alt= van <img> 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.

Tabellen en lijsten

Handleidingen ondersteunen een eenvoudige tabel-syntax gelijkaardig aan die van HTML. Om een tabel te starten gebruik je een <table> element. Je start een regel met het <tr> element. Indien je echter tabeldata wil invoegen gebruiken we niet het <td> element, maar <th> indien je een hoofding toevoegt en <ti> indien je normale data toevoegt. Je kan <th> overal gebruiken waar je een <ti> kan gebruiken -- er is geen verplichting om <th> 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 caption= attribuut voor <table>).

Om een geordende of ongeordende lijst te maken gebruik je de HTML-elementen <ol>, <ul> en <li>. Dergelijke lijsts mogen enkel binnenin een <p>, <ti>, <note>, <warn> of <impo> element voorkomen.

Intra-document referenties

De handleiding-stijl maakt het zeer eenvoudig referenties te maken naar andere delen in het document via hyperlinks. Je kan een link naar Hoofdstuk 1 maken met <uri link="#doc_chap1">Hoofdstuk 1</uri>. Om naar sectie 2 van hoofdstuk 1 te wijzen type je <uri link="#doc_chap1_sect2>sectie 2 van hoofdstuk 1</uri>. Om naar figuur 3 in hoofdstuk 1 te wijzen, type je <uri link="#doc_chap1_fig3">figuur 1.3</uri>. Of je verwijst naar code listing 2 in hoofdstuk 2 met <uri link="#doc_chap2_pre2">code listing 2 in hoofdstuk 2</uri>. We gaan later nog andere auto-link mogelijkheden (zoals tabellen) toevoegen.

3.  Referenties

Start uw creativiteit

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 gentoo-doc mailinglist waarin je dan vermeldt wat je wil schrijven. Veel plezier!



Print

Upgedate op 13 Mei 2003

De originele versie van dit document was laatst geupdate om 7 oktober 2012

Korte inhoud: 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.

Daniel Robbins
Author

John P. Davis
Author

Jorge Paulo
Editor

Sven Vermeulen
Translator

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.