LDP WikiText Editing HOWTO
David Merrill
<[1]david@lupercalia.net>
Vertaald door: Ellen Bokhorst
<[2] bokkie@nl.linux.org>
23-01-2002
Wijzigingen
Herziening 1.1 28-01-2002 Herzien door: dcm
Een vraag en antwoord sectie toegevoegd, moest de grammatica van
markup voor bestandsnamen verbeteren.
Herziening 1.0 23-01-2002 Herzien door: dcm
Initiële release.
In deze HOWTO wordt uitgelegd hoe het LDP WikiText bewerkingsformaat
te gebruiken om DocBook documenten voor het LDP aan te maken.
_________________________________________________________________
Inhoudsopgave
[3]Wettigheden
[4]Introductie
[5]Wat is een Wiki?
[6]Waarom zou ik het willen gebruiken?
[7]Hoe werkt het?
[8]Maar hoe zit het met de meta-data?
[9]Waar is het? Kan ik toegang krijgen?
[10]Conclusie
Wettigheden
Dit document is auteursrechtelijk beschermd © 2002, David Merrill, en
het is beschikbaar onder de voorwaarden van de GNU Free Documentation
License, zonder invariant secties, zonder front-cover en zonder
back-cover.
_________________________________________________________________
Introductie
Voor nieuwe documenten gebruikt het LDP het [11]DocBook formaat, en we
proberen oudere documenten ook naar DocBook om te zetten. Helaas is
DocBook een zeer grote en complexe DTD, dus kan het moeilijk voor
mensen zijn het te gebruiken. We zijn altijd op zoek naar manieren om
het makkelijker te maken, zodat meer mensen de LDP kunnen helpen.
De oplossing waarmee we kwamen werd geïnspireerd door het WikiWikiWeb,
met dank aan een geweldige suggestie van de LDP auteur Martin Wheeler.
Ik noem het WikiText, omdat het geen echte Wiki is, maar het een
aantal van de beste features heeft van een echte Wiki.
_________________________________________________________________
Wat is een Wiki?
Een Wiki is een soort website, waar iedereen die de site leest, het
ook kan wijzigen. Ondanks dat de LDP niet van plan is een dergelijke
geoorloofde bewerking te implementeren, vinden we wel de wijze waarop
het Wiki bewerken werkt plezierig. In plaats van het leren van html
tags, voer je de informatie in gewone tekst in. De Wiki software neemt
die gewone tekst over en zet het om in html om het weer te geven.
In ons geval converteren we het niet naar html, maar naar DocBook.
Vervolgens wordt die DocBook doorgegeven aan onze reguliere
publicatiesystemen net alsof je het oorspronkelijk in DocBook had
geschreven. Wanneer je er nog nooit eerder gebruik van hebt gemaakt,
kijk dan eens op [12]http://www.wikipedia.com voor een goed voorbeeld
van een bloeiende Wiki.
Algemene functies zoals het aanmaken van een link, een lijst voorzien
van opsommingstekens, een genummerde lijst en kopteksten van secties,
worden snel en makkelijk aangemaakt. We wilden in het zelfde
gemaksniveau voorzien voor LDP auteurs, dus schreef ik een utility dat
een tekstformaat zou accepteren dat vergelijkbaar is met dat in Wikis
(we noemen het WikiText) om het vervolgens te combineren in de [13]LDP
Database om DocBook te genereren.
_________________________________________________________________
Waarom zou ik het willen gebruiken?
Hier zijn een aantal redenen:
1. Het gaat snel en eenvoudig. Geen grillige tags te leren, alleen
een paar simpele tekstaanwijzigen.
2. Het is krachtig. Terwijl je WikiText kunt bewerken zonder ook maar
enig DocBook gebruiken, kun je het ook gebruiken om elke DocBook
tag daarbinnen te gebruiken.
3. Het houdt versies bij. Een complete versie history van je
wijzigingen wordt bijgehouden in de database. Je kunt naar een
eerdere versie terugkeren als je iets deed wat je niet wilt. Je
kunt dit ook met cvs doen, maar het is in het online systeem veel
makkelijker.
4. Het kan documenten delen. Auteurs die samen met andere documenten
aan documenten werken kunnen via de WikiText samenwerken. Ja, cvs
kan dit ook, maar nogmaals WikiText is eenvoudiger.
5. Het is toegankelijk. Je hebt alleen een webbrowser en een LDP
Database account nodig.
6. Het is WYSIWYG. Er is een "Preview" feature, dus je kunt op de
"Preview" knop klikken en bekijken hoe je document er uit zal gaan
zien op de LDP-site. Er zijn geen uit te voeren utility's, er
hoeft niets te worden geleerd, er hoeven geen DTD's te worden
geïnstalleerd of catalogus bestanden om mee te stoeien. Als je
ooit probeerde om een werkend DocBook systeem op je systeem te
krijgen, dan zul je dit waarderen! :-)
_________________________________________________________________
Hoe werkt het?
We probeerden dezelfde tekstaanwijzingen te gebruiken die op de
Wikipedia worden gebruikt, welke afkomstig is van UseModWiki. Er zijn
een aantal verschillen in Wiki systemen, maar de meeste zijn zeer
vergelijkbaar met deze, en het heeft zichzelf bij ons reeds bewezen.
Een lege regel scheidt paragrafen, en er zijn nog wat andere
aanwijzingen om secties, opsommingslijsten, links, bestandsnamen, enz
te maken.
_________________________________________________________________
Secties
=Introductie|intro=
maakt een nieuwe sectie aan op het hoogste niveau. Zie het pipe teken
gevolgd door "intro"? Veel aanwijzingen voorzien in een "id", en dit
is de wijze waarop je erin voorziet. Voor secties zal het id de naam
zijn van het uitvoerbestand (intro.html in het eerste voorbeeld), of
de html "tag" gebruikt voor links binnen het document.
==Hoe werkt het?|how-does-it-work==
maakt een sectie op het tweede niveau aan, en
===Waarom zou ik het gebruiken?|why?===
maakt een sectie aan op het derde niveau.
_________________________________________________________________
Lijsten
Genummerde lijsten
#één
#twee
#drie
/#
De "#" prefix geeft aan een genummerde lijst te maken. De genummerde
lijst gaat verder tot aan het einde van de huidige sectie, of totdat
het een regel tegenkomt met slechts "/#", waarmee de lijst wordt
afgesloten. Na het openen van een andere "#" lijst, zal de nummering
weer bij "1" beginnen.
Het bovenstaande blok zal er in het uiteindelijke document zo uit
komen te zien:
1. één
2. twee
3. drie
_________________________________________________________________
Opsommingslijsten
Opsommingslijsten werken bijna hetzelfde, behalve dat je de aanwijzing
"*" gebruikt, en je je geen zorgen hoeft te maken over het
hernummeren:
*één
*twee
*drie
/*
Het bovenstaande blok zal er in het uiteindelijke document zo uit
komen te zien:
* één
* twee
* drie
_________________________________________________________________
Links
Gebruik de vierkante haken om links te identificeren, zoals in:
[[http://www.linuxdoc.org|Linux Documentatie Project]]
In dit geval is de tekst na het pipe teken geen id, maar de "titel"
van de link.
Er zijn twee speciale namespaces die je kunt gebruiken naast de
standaard "http:" en "mailto:" namespaces die je waarschijnlijk reeds
kent. De eerste is de "ldp:" namespace. Bekijk de volgende link eens:
[[ldp:Distributions-HOWTO]]
Wanneer je gebruikt maakt van de namespace "ldp:" zal WikiText het
document dat je hebt benoemd opzoeken in de LDP-database en er een
link naar genereren.
Noot: we werken nog steeds aan het invoeren van de juiste "naam" in
alle databaserecords, dus slechts een paar werken. Maar maak je geen
zorgen. Laat ons gewoon weten als je een link wilt gebruiken die nog
niet correct is en we zullen het onmiddellijk corrigeren.
De tweede speciale namespace is de "wiki:" namespace. Het zal een link
genereren naar het artikel in de Wikipedia, een open source
encyclopedie project. We hopen een aantal van de meest van toepassing
zijnde artikelen uit de Wikipedia direct op de LDP te linken.
Wikipedia heeft heel veel geweldige artikelen over aan computer
gerelateerde onderwerpen. Niet het soort informatie die we bij de LDP
verzorgen, maar wel wat onze documenten zeer goed zou aanvullen. Er
staan bijvoorbeeld artikelen in over virtueel geheugen,
besturingssystemen, enzovoort. Thans gaat je link naar de live
Wikipedia site. Mogelijk zal het naar een mirror op onze site gaan,
maar met een link naar de "echte" site.
De volgende links gaan naar artikelen genaamd "Operating system" en
"Linux kernel" in de Wikipedia:
[[wiki:Operating system]]
[[wiki:Linux kernel]]
Wikipedia is een geweldige bron voor alle Net-gebruikers. Zowel de
software die ze gebruiken als de inhoud is open source.
_________________________________________________________________
Bestandsnamen
Bestandsnamen kun je aangeven door ze tussen dubbele aanhalingstekens
te plaatsen, net als http en andere links. Of je kunt de "file"
namespace specificeren:
[[/etc/apache/httpd.conf]]
[[file:/etc/apache/httpd.conf]]
Voor beide manieren zal het worden weergegeven als:
/etc/apache/httpd.conf.
_________________________________________________________________
Nadruk
Je kunt bepaalde woorden benadrukken, door ze te omsluiten tussen drie
(3) enkele aanhalingstekens, zoals in:
'''Wauw!'''
Dat zal worden weergeven als: Wauw!
_________________________________________________________________
QandASets
Je kunt vraag en antwoord-sets creëren als je een FAQ aan het
schrijven bent, of een FAQ sectie in je document hebt. Gebruik gewoon
"Q:" en "A:" als de eerste tekens op een nieuwe regel en de QandASet
tags zullen automatisch worden aangemaakt.
Q: Wat als je iets wilt met DocBook dat niet door WikiText wordt ondersteund?
A: Mu.
En zo wordt het voorbeeld weergegeven. Precies voor de eerste vraag
verschijnt een lijst met vragen. In het voorbeeld ziet dit er wat raar
uit, aangezien er slechts één vraag staat en het precies twee keer
wordt weergegeven. Als je echter aan de [14]Linux-FAQ werkt, ziet het
er echt fraai uit.
Vraag: [15]Wat als je iets wilt met DocBook dat niet door WikiText
wordt ondersteund?
Vraag: Wat als je iets wilt met DocBook dat niet door WikiText wordt
ondersteund?
Antwoord: Mu. Zie de volgende sectie.
_________________________________________________________________
Fancy Stuff
Er is geen DocBook structuur die niet door WikiText wordt ondersteund.
Waarom? Omdat wanneer er geen WikiText voor is, je gewoon de benodigde
tags direct in het document zal plaatsen, en ze zullen gewoon werken.
Er zijn een paar "speciale" tags die niet tot de inline DocBook
behoren, maar secties structureren, waaronder de "programlisting" en
"screen" tags. Je moet onthouden dat geen van de WikeText functies
binnen deze tags zal werken. Je wilt toch niet dat je commentaarregels
in je voorbeeldcode wordt geconverteerd naar genummerde lijsten,
nietwaar?
# dit is commentaar
# het is GEEN genummerde lijst!
_________________________________________________________________
Maar hoe zit het met de meta-data?
Je hoeft geen articleheader of articleinfo tag informatie in je
document in te voeren. Die informatie wordt direct uit de database
zelf gehaald. Ga naar de bewerkpagina van je document en vul daar de
van toepassing zijnde informatie in.
_________________________________________________________________
Waar is het? Kan ik toegang krijgen?
Elke LDP auteur is welkom de WikiText te gebruiken. Het bevindt zich
in de LDP-database, [16]http://db.linuxdoc.org. Je zult een account
nodig hebben voor de database. Als je er nog geen hebt, kun je hier
per e-mail om verzoeken. Stuur me je volledige naam (zoals deze
verschijnt in je documenten), je gebruikersnaam en wachtwoord, en ik
stel het waarschijnlijk nog dezelfde dag voor je in.
Zodra je bent ingelogd op de database, klik je op "My Documents". Als
je geen lijst ziet van alleen je eigen documenten, dan heb ik er een
knoeiboel van gemaakt. :-)
Klik op het document dat je wilt wijzigen. Je zult een pagina zien die
de meta-data toont die we hebben voor het document. Op die pagina
staat ook een link naar WikiEdit. Klik erop en je bent op weg.
Klik op "Preview" om te zien hoe je document er uit zal gaan zien bij
de LDP (behalve dat het op een enkele pagina zal worden weergegeven).
Klik op "DocBook" om de raw DocBook te bekijken die WikiText van je
tekst heeft gegenereerd.
Klik op "Save" om je wijzigingen in de database op te slaan. Je kunt
ook een "opmerking" toevoegen, voor een toekomstige referentie.
Klik op "Version History" om een record te zien van alle wijzigingen
die je hebt aangebracht aan het document.
_________________________________________________________________
Conclusie
We hopen dat je vindt dat de WikiText je leven er als auteur
makkelijker op maakt, zodat je je kunt concentreren op het schrijven
van de best mogelijke documentie en minder tijd hoeft te spenderen aan
het in elkaar flansen van je tools en het leren van een geheimzinnige
syntax.
Ik zou feedback of suggesties van jullie van harte waarderen, of het
nu positief of negatief is (zolang het maar constructief is
uiteraard). Je kunt me schrijven via [17]david@lupercalia.net.
References
1. mailto:david@lupercalia.net
2. mailto: bokkie@nl.linux.org
3. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#LEGAL
4. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#INTRO
5. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#WHATS-A-WIKI
6. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#WHY-WIKI
7. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#HOW-DOES-IT-WORK
8. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#META-DATA
9. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#USE-IT
10. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#CONCLUSION
11. http://www.docbook.org/
12. http://www.wikipedia.com/
13. http://db.linuxdoc.org/
14. http://www.linuxdoc.org/FAQ/Linux-FAQ/
15. file://localhost/tmp/WikiText-HOWTO-NL/WikiText-HOWTO-NL.html#AEN139
16. http://db.linuxdoc.org/
17. mailto:david@lupercalia.net
