Next Previous Contents

4. Leren van LinuxDoc

4.1 Introductie

LinuxDoc is heel wat makkelijker te leren dan DocBook. Maar het meeste van wat je over LinuxDoc leert, zal ook bruikbaar zijn voor DocBook. Dus mocht je eventueel besluiten op DocBook over te gaan, dan zal de meeste energie die je in het leren van LinuxDoc hebt gestoken niet zijn verspild.

Een manier om te leren is door middel van voorbeelden. Ik heb 3 voorbeeldbestanden geschreven variërend van eenvoudig tot gevorderd. Begin met Voorbeeld1. Deze bestanden zijn hier opgenomen als secties. Om ze naar individuele bestanden om te zetten zou je de tekst eruit kunnen knippen en naar bestanden weg kunnen schrijven. Je zou dan kunnen proberen ze in tekst om te zetten met de opdracht "sgml2txt -f voorbeeld2.sgml" om te bekijken hoe dat eruit ziet. Zorg dat de bestandsnamen op .sgml eindigen.

Ga naar een LDP-mirrorsite, zoek de HOWTO's op en selecteer LinuxDoc SGML als je een aantal echte voorbeelden wilt bekijken. Of ga direct naar de hoofdsite: http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/sgml Voor nu het eerste eenvoudige voorbeeld.

4.2 Voorbeeld 1

<!doctype linuxdoc system>
<article>
<title>Eerste voorbeeld (voorbeeld1)
<author>David S.Lawyer  

<sect> Introductie
<p> Dit is een erg simpel voorbeeld van de "broncode" voor het LinuxDoc
tekstopmaaksysteem. Deze paragraaf begint met een paragraaftag (een "p"
omsloten door punthaken). Merk op dat er ook nog andere tags zijn die ook
door punthaken worden omsloten. Als je geen tags ziet, dan lees je dus
een geconverteerd bestand, dus ga op zoek naar het bronbestand:
voorbeeld1.sgml (die met de tags). 

Dit is de volgende paragraaf. Het wordt slechts door een lege regel gescheiden
van de voorgaande paragraaf. De "p" tag is alleen nodig voor de eerste
paragraaf van een sectie (net na de sect-tag). De bestandsextensie:
sgml staat voor Standard Generalized Markup Language. Je bent nu de LinuxDoc
variant van sgml aan het lezen, wat op de allereerste regel van dit bestand
is opgegeven.

<sect> Tags
<p> Tags is al datgene dat tussen punthaken staat. De "sect" tag hierboven
markeert het begin van een nieuwe sectie van dit voorbeelddocument.
"Introductie" was de eerste sectie en je bent nu de tweede sectie
getiteld "Tags" aan het lezen. Als dit een lang document zou zijn (zoals
een boek) zou een sectie corresponderen met een hoofdstuk.

Aan het begin van dit artikel staan "article", "title" en "author".
Aan het einde van dit artikel staat een "/article" tag die het einde
van dit artikel markeert. Dus er staat een paar "article"
tags, als eerste de begintag en de tweede de eindtag. Dus dit gehele
artikel wordt omsloten door "article" tags. In latere voorbeelden zul
je zien dat net als bij deze nog andere tags in paren voorkomen. Ze beïnvloeden
wat zich tussen de paren (begin- en eindtag) bevindt. Elke tagnaam met
net ervoor een "/" is een "eindtag".

Wanneer deze broncode naar een ander formaat wordt geconverteerd (zoals
gewone tekst met het programma sgml2txt) worden de tags verwijderd. Tags dienen
alleen voor het sgml2txt programma om de conversie uit te kunnen voeren.
Er zijn meer tags te leren. Dus ga alsjeblieft verder met het volgende
voorbeeld: voorbeeld2, zodra je dit voorbeeld1 begrijpt.
Je hoeft de tags niet echt te onthouden, aangezien
ze in latere voorbeelden zullen worden herhaald (maar dan zonder of
met weinig uitleg).
</article>

4.3 Voorbeeld 2

<!-- Dit is een opmerking. Het wordt genegeerd wanneer het bronbestand
naar andere formaten wordt omgezet. -->
<!-- De volgende vereiste tag impliceert dat dit bestand in 
LinuxDoc is opgemaakt -->
<!doctype linuxdoc system>

<article>

<title>Tweede Voorbeeld (voorbeeld2)
<author>David S. Lawyer
<date>v1.0, juli 2000

<abstract>
Dit is de samenvatting. Dit document is het tweede voorbeeld over het
gebruik van de Linuxdoc SGML variant van sgml. Het is wat complexer dan
het eerste voorbeeld (voorbeeld1.sgml), maar eenvoudiger dan het derde
voorbeeld (voorbeeld3.sgml). Na je onderzoek zul je een simpele HOWTO
in LinuxDoc kunnen schrijven. Einde samenvatting.
</abstract>

<!-- De "toc" = Inhoudsopgave.  Het zal hier worden aangemaakt. -->
<toc>

<!-- Begin het hoofdgedeelte van het artikel (of document) hier. Het deel
hierboven is een soort lange header. -->

<sect>Het Tweede voorbeeld (voorbeeld2.sgml)

<p>Tenzij je bekend bent met markup talen, zou je eerst voorbeeld1.sgml
moeten lezen. Wellicht dat je deze voorbeeldbestanden door een vertaalprogramma,
zoals sgml2txt, wilt laten verwerken, om ze naar tekst te converteren om te
zien hoe anders het resultaat er uitziet in vergelijking met dit
"brondocument" met al zijn tags.

<sect>Lay-out van een artikel
<sect1>Document Header
<p> Een manier om een headerdeel aan te maken is door deze gewoon vanuit
een ander .sgml bestand te kopiëren. Vervang dan alles behalve de tags
door de juiste info voor je document. Dit is net als het gebruik van een
"sjabloon".

<sect1>Inhoud van het document
<p>
Na de header komt de inhoud van het document, bestaande uit geneste secties
gemarkeerd door sect-tags. Subsecties worden gemarkeerd door sect1-tags.
Aangezien dit de eerste subsectie is binnen de 2e hoofdsectie, is het in
feite sectie 2.1. Binnen een subsectie kunnen sub-subsecties voorkomen gemarkeerd
door sect2-tags, enz. Voor een sub-sub-sub-sectie gebruik je "sect3".
Er zijn zelfs tags als sect4 en sect5, maar het is zeer
onwaarschijnlijk dat je ze nodig zult hebben.

<sect2> Dit is een sub-sub-sectie
<p>
Het is 2.2.1.  Een "p" tag mag op een eigen regel worden gebruikt.
Dit wijzigt niets in het resulterende document.

<sect> Meer mogelijkheden in voorbeeld3
<p> Met de tags in dit voorbeeld2 kun je een simpel kort document
van een paar pagina's lang schrijven. Maar voor langere documenten of voor
andere belangrijke mogelijkheden zoals het plaatsen van links in documenten,
moet je het volgende voorbeeld bestuderen: voorbeeld3. 
Het laat je zien hoe je lijsten en fonts kunt creëren.
</article>

4.4 Voorbeeld 3

<!doctype linuxdoc system>
<!-- Let op de mailto: na mijn naam. Hier kan de lezer op klikken om
me email te sturen -->

<article>
<title>Derde voorbeeld (voorbeeld3)
<author>David S. Lawyer <url url="mailto:dave@lafn.org">
<date>v1.0, juli 2000
<abstract>
Dit document is het derde voorbeeld over het gebruik van de LinuxDoc variant
van sgml. Het is complexer dan het tweede voorbeeld.
</abstract>
<!-- Opmerking: toc = Inhoudsopgave  -->
<toc>

<sect> Fonts
<p> 
Ondanks dat er in een gewone tekstuitvoerversie niets van is te zien,
werkt het wel voor andere conversies.
<bf>vet</bf>   <em>benadrukt</em>     <sf>sans serif</sf>
<sl>slanted font</sl>    <tt>typewriter font</tt>   <it>schuindruk</it>
Een andere manier om dezelfde fonts te krijgen is door de tekst te omsluiten
door slashes zoals in:
<bf/vet/              <em/benadrukt font/      <sf/sans serif/
<sl/slanted font/     <tt/typewriter font/     <it/schuindruk/ 

<sect> Links <label id="links_">
<p> Je kunt links creëren (iets waar onder htmlbrowsers op kan worden
geklikt om naar elders te gaan). Ze kunnen naar een ander deel van dit
document (kruisverwijzingen) gaan of naar een website op het Internet.

<sect1> Kruisverwijzingen
<p> Als je op <ref id="links_" name="Links"> klikt, zal je worden
gebracht naar het begin van de "Links" sectie hierboven (gelabeld met links_).
Het label-id kan elk uit te kiezen woord zijn, maar het is verstandig
algemene woorden te vermijden zodat je kunt zoeken op unieke labels met
je editor. Daarom gebruik ik links_ (met het onderstrepingsteken). De
naam van deze link zal (in html opmaak) worden weergegeven als de naam
waarop kan worden geklikt. Deze naam (Links) zal ook in de tekstweergave
verschijnen.

<sect1> URL Links
<p> Als je op <url url="http://www.linuxdoc.org"> klikt, kom je bij
de website van het Linux Documentatie Project. Hierna volgt een link
waaraan een naam is toegevoegd waar mensen op zullen klikken:
<url url="http://www.linuxdoc.org" name="Linux Documentation Project">. 
Als je deze tweede methode gebruikt, dan hoef je zelfs niet uit te leggen
waarnaartoe deze link leidt, aangezien dit duidelijk uit de naam blijkt.

<sect> Verboden tekens
<p> Alles wat je intikt binnen punthaken zal als een tag worden
geïnterpreteerd. Maar wat als je een tag in een document wilt
laten zien? Hierbij gebruik je voor de punthaken een codewoord.

Voor de < kun je $amp;lt gebruiken en voor de > $amp;gt. 
lt betekent less than (kleiner dan) en gt greater than (groter dan). Hier is
bijvoorbeeld een p-tag: &lt;p&gt;.  Natuurlijk wordt hiermee
in werkelijkheid geen paragraaf gestart, maar het zal in het geconverteerde
document verschijnen als een <p>. Deze codes beginnen allen met een &-teken.
De ; na de lt is om het te scheiden. Het is niet nodig als er een spatie
achter staat. Bijvoorbeeld: 3 &lt 4.  In feite is het zo dat als je
weet dat het OK is om een niet gepaarde > te gebruiken, je het zou kunnen
schrijven als
<p> &lt;p>. Dit zal niet per abuis worden herkend als een tag
aangezien er geen openings < is.

Er zijn ook nog andere tekens die je niet direct in de tekst kunt plaatsen.
Voor & in een AT modem opdracht gebruik je: AT&amp;. Zie
voorbeeld3 of de "guide" die met linuxdoc-tools of sgml-tools wordt
meegeleverd als er nog andere tekens zijn die problemen opleveren.

<sect> Verbatim, Code & Newline
<sect1> Verbatim
<p> Als je er zeker van wilt zijn dat tijdens de conversie naar andere
formaten bepaalde regels niet samen worden gevoegd, gebruik je verbatim (verb).
Een aantal zaken worden nog steeds herkend, ook al staan ze binnen de 
verbatim tags. Dit zijn onder andere de macro's beginnend met & en eindtags
beginnend met /.

<tscreen><verb>
% sgml2txt -f example.sgml 
</verb></tscreen>
De "tscreen" stelt het font in op typewriter en zorgt dat de tekst fraai
inspringt.

<sect1> Code
<p> Hiermee wordt computercode omsloten door twee lijnen.
<tscreen><code>
Plaats hiertussen computerbroncode
</code></tscreen>

<sect1> Newline
<p> Om een newline te forceren gebruik je <newline>
Deze zin begint altijd aan de linkermarge.

<sect>Lijsten
<p>
Hiermee worden items in een lijst geplaatst met aan het begin van elk item
een markering. Ze beginnen met de "itemize" tag.
<itemize>
<item> Dit is het eerste item in een lijst.
<item> Dit is het tweede item
       <itemize> 
       <item> Meerdere niveaus (nesten) wordt ondersteund.
       <item> Het tweede item in deze sublijst
       </itemize>
       <enum>
       <item> Genummerde lijstem met gebruik van <tt/enum/ werkt ook.
       <item> Dit is itemnummer 2
       </enum>
<item> Het laatste item in de hoofdlijst
</itemize>
</article>

4.5 LinuxDoc beknopte referentiesheet

Header deel

<!doctype linuxdoc system>
<article>
<title>Beknopte referentiesheet
<author>David S. Lawyer
<date>v1.0, juli 2000
<abstract> samenvatting hier </abstract>
<toc> <!-- Opmerking: toc = Inhoudsopgave  -->

Lay-out van de inhoud

<sect> Hoofdstuk 1         Noot: Plaats een <p> op de eerste regel van 
<sect1> Subsectie 1.1      iedere sectie (of subsectie, enz.)
<sect1> Subsectie 1.2
<sect> Hoofdstuk 2         Kies namen van titels ter vervanging van "Hoofdstuk"      
<sect1> Subsectie 2.1      "Subsectie", enz.
<sect2> Sub-subsectie 2.1.1
<sect2> Sub-subsectie 2.1.2
<sect1> Subsectie 2.2
</article>

Fonts

Hier zijn twee manieren voor:

<bf>boldface font</bf>   <em>emphasis font</em>     <sf>sans serif font</sf>
<sl>slanted font</sl>    <tt>typewriter font</tt>   <it>italics font</it>
<bf/boldface/    <em/emphasis/     <sf/sans serif/
<sl/slanted/     <tt/typewriter/   <it/italics/  

Lijsten (nesten is OK)

Opsommingen:                            Genummerde lijst:
<itemize>                               <enum>
<item> Eerste item                      <item> Eerste item
<item> Tweede item                      <item> Tweede item
<item> enz.                             <item> enz.
</itemize>                           </enum>

Links

   Kruisverwijzingen:                           Een Email Link:
<ref id="links_" name="Links">          <url url="mailto:bob@linuxdoc.org">

Newline, Verbatim, URL's

Om een newline te forceren <newline>
<tscreen><verb>
<url url="http://www.linuxdoc.org">
<url url="http://www.linuxdoc.org" name="Linux Documentatie Project">.
</verb></tscreen>

Tekencodes (macro's).


Next Previous Contents