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. | ||
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.
Voor nieuwe documenten gebruikt het LDP het 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.
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 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 LDP Database om DocBook te genereren.
Hier zijn een aantal redenen:
Het gaat snel en eenvoudig. Geen grillige tags te leren, alleen een paar simpele tekstaanwijzigen.
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.
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.
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.
Het is toegankelijk. Je hebt alleen een webbrowser en een LDP Database account nodig.
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! :-)
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.
=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.
#éé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:
één
twee
drie
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 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.
Je kunt bepaalde woorden benadrukken, door ze te omsluiten tussen drie (3) enkele aanhalingstekens, zoals in:
'''Wauw!''' |
Dat zal worden weergeven als: Wauw!
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 Linux-FAQ werkt, ziet het er echt fraai uit.
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! |
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.
Elke LDP auteur is welkom de WikiText te gebruiken. Het bevindt zich in de LDP-database, 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.
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 david@lupercalia.net.