De Documentatie-HOWTO-NL

Wat zijn HOWTO's?

HOWTO's zijn documenten die stap-voor-stap een bepaald onderwerp beschrijven. Je kunt hierbij denken aan de installatie van een bepaald Linux-package, de configuratie ervan en eventuele oplossingen voor problemen die zich daarbij voor kunnen doen. De documenten worden vaak in verhalende vorm geschreven en soms tref je aan het einde van het document een paragraaf aan met veel gestelde vragen en antwoorden. Kortom, documenten om je wegwijs te maken in de Linux-wereld. HOWTO's worden geschreven door vrijwilligers, mensen die hun kennis willen delen met mede-Linuxgebruikers of om de nog beginnende Linux-gebruikers op weg te helpen.

Niet meer beheerde/verouderde HOWTO's

Veel documentatie, die in het verleden werd geschreven, is nog steeds via het Internet te verkrijgen. Echter deze documentatie wordt door allemaal vrijwilligers geschreven en het kan dus gebeuren dat je documentatie aantreft die niet meer door iemand wordt beheerd. Het gevolg hiervan is dat zolang niemand het beheer van een dergelijk document op zich neemt, er wat verouderde informatie in kan staan. Hierbij kun je denken aan een beschrijving van inmiddels verouderde packages, maar ook aan hyperlinks die verwijzen naar overige (voorheen) op het Internet verkrijgbare informatie. Toch kan het lezen van dergelijke informatie nog wel zinvol zijn. Het kan je op z'n minst op ideeën brengen over hoe je een bepaald probleem aan kunt pakken. Documenten waarvan de auteur heeft aangegeven ze niet meer te willen/kunnen beheren of die met een zeer oude datum zijn vaak terug te vinden in een aparte directory, vaak één met de naam "unmaintained" of iets dergelijks.

Inhoud van een HOWTO

De naam van een HOWTO zegt vaak niet alles over de inhoud ervan. Hiermee wil ik je zeggen dat als het onderwerp je niet interesseert, het toch nuttig kan zijn om dat document te lezen. In veel HOWTO's zijn namelijk vaak tips en truuks opgenomen die ook op andere vlakken hun nut kunnen hebben. Als je op zoek bent naar informatie over een specifiek onderwerp of bepaalde opdracht, dan is het onder Linux heel eenvoudig om snel op te zoeken in welke documentatie je daarover informatie kunt vinden. Voor HOWTO's die zich in één directory bevinden zou je hiervoor bijvoorbeeld de opdracht grep kunnen gebruiken. Als voorbeeld geef ik hieronder een zeer eenvoudig grep-commando waarmee je kunt zoeken naar die documenten waarin het begrip mount voorkomt:

grep -ir mount *

In de uitvoer wordt als eerste de bestandsnaam weergegeven, waarin het gezochte woord werd gevonden, vervolgens de volledige zin waarin het gezochte woord voorkomt. Hieruit zou je al enigszins op kunnen maken in welk van de gegeven documenten hetgeen staat, wat je zoekt. De meegegeven optie `i' betekent dat grep geen onderscheid zal maken tussen hoofdletters en kleine letters. De optie `r' zoekt tevens in de onderliggende subdirectory's, wat een recursieve search wordt genoemd.

Het gebeurt weleens dat HOWTO's worden opgesplitst in meerdere documenten of dat meerdere HOWTO's worden samengevoegd tot één document, waarbij de naam van de HOWTO wordt gewijzigd. Als gevolg hiervan kan het dus zijn dat je dubbele informatie aantreft.

Waar vind je Linux-HOWTO's?

Op diverse plaatsen op het Internet kunnen Linux-HOWTO's worden verkregen. Een belangrijke plaats is bv:

http://www.tldp.org

waar auteurs uit de hele wereld hun zelfgeschreven of vertaalde versies van reeds bestaande HOWTO's laten archiveren en publiceren. Ook worden er boeken uitgegeven waarin (meestal oude) versies van de Linux-HOWTO's staan afgedrukt.

Het merendeel aan Nederlandstalige HOWTO's is te vinden op:

http://doc.nl.linux.org/HOWTO

HOWTO's en mini-HOWTO's

In navolging van de LDP werd voorheen een splitsing gemaakt tussen mini-HOWTO's en HOWTO's om verschillen in de omvang van het document aan te duiden. Dit onderscheid wordt sinds begin 2003 niet meer gemaakt. Wel staat het de auteurs vrij nog altijd het woord `mini-' in de naam van hun document te gebruiken. Hier wordt echter geen speciale betekenis meer aan gehecht.

Wat is een GUIDE

Een GUIDE is veelal een omvangrijk document waarin een bepaald onderwerp wordt gekozen om over te schrijven. Op het gekozen onderwerp wordt vaak wat dieper ingegaan dan in HOWTO's. Deze GUIDE wordt vervolgens door de auteur op Internet gepubliceerd. Je kunt dit vergelijken met een boek, zoals één over systeembeheer, een bepaalde distributie, enzovoort. Diverse GUIDE's zijn ook daadwerkelijk als boek uitgegeven en dus in papieren vorm te koop bij een computer- of boekwinkel. Een voorbeeld hiervan is de Network Administration Guide, vaak afgekort tot NAG, die in boekvorm is uitgegeven. Soms wordt een GUIDE slechts deels op Internet gepubliceerd en mocht je geïnteresseerd zijn in het gehele boek dan rest je niet anders dan in je buidel te tasten. Het gebeurt regelmatig dat dan een deel van de opbrengst van het boek wordt gedoneerd aan een documentatieproject, dus weer terugkomt in de Linux-gemeenschap. GUIDE's worden over het algemeen geschreven in teX-formaat of in SGML of XML volgens een bepaalde DTD (vaak DocBook). Meestal worden verschillende formaten beschikbaar gesteld, zodat je de mogelijkheid hebt het document off-line te lezen en/of af te drukken.

Waar vind je Linux-GUIDE's?

Net als Linux-HOWTO's, zul je op http://www.tldp.org een aantal Linux-GUIDE's aantreffen. Er is echter meer, maar vaak kun je hier het beste via een zoekmachine, zoals Google naar zoeken. Tik in het invoerveld gewoon in wat je zoekt, aangevuld met "guide". Hieronder tref je een kleine selectie aan van GUIDE's/Boeken waar je wellicht wat aan kunt hebben:

Linux Administration Made Easy guide Linux Installation and Getting Started The CVS Book, Open Source Development with CVS Beginner's Guide to CGI Scripting with Perl Hoofdstuk 20 van het boek: Computer Science and Perl Programming MH & nmh: Email for Users & Programmers Advanced Linux Programming GTK+ / Gnome Application Development Linux Device Drivers, 2nd Edition The GNU Awk User's Guide GNU Autoconf, Automake, and Libtool

Er zijn nog niet zo heel veel anderstalige GUIDE's vertaald naar het Nederlands, omdat dit enorm veel tijd kost. Een GUIDE bestaat al snel uit meer dan 100 pagina's. Soms wordt ervoor gekozen een vertaling op te pakken met een groep zodat een ieder een deel van de GUIDE op zich neemt om te vertalen. Vertalingen van een aantal GUIDE's zijn in ieder geval te vinden op:

http://doc.nl.linux.org/GUIDE

en in diverse formaten te downloaden vanaf:

ftp.nl.linux.org

Wat is een infopage

Een infopage is een beknopte handleiding van een bepaalde opdracht of bepaald programma. Vaak worden meerdere opdrachten in één infopage behandeld. Je vindt hierin een uitleg van de opdracht/het programma met de mogelijke opties, vaak wat uitgebreider en recenter als in een manpage. De source van de infopage heeft de extensie .texi. Je kunt de source downloaden om op je computer onder Linux te bekijken met het programma info nadat deze is omgezet met het programma makeinfo. Om dit document ook online te kunnen lezen is het voor je gemak op de site in HTML formaat weergegeven.

Vertalingen

Er wordt hard aan gewerkt om beschikbare Linux-documenten te vertalen naar het Nederlands. Per document kost dit tijd en inzet en er wordt daarom prioriteit gegeven aan de beginnersdocumenten.

Aangezien diverse mensen zich bezighouden met deze vertalingen, ontstaan er verschillen in computertermen die wel of niet worden vertaald. Veel van deze begrippen zijn als Engelse term algemeen ingeburgerd, waardoor voor velen (zeker voor programmeurs) de Engelse term meer duidelijkheid zal scheppen dan wanneer een vertaalde vorm ervan zal worden gebruikt. Toch zal zoveel mogelijk worden getracht, begrippen te vertalen om ook tegemoet te komen aan een beginnende gebruiker. Vind je een vertaald begrip erg storend, waardoor het geheel onduidelijk wordt, laat dan alsjeblieft iets van je horen. Het is namelijk de bedoeling dat een vertaling het je makkelijker maakt, als je de voorkeur geeft aan het lezen van de Nederlandstalige versie, niet moeilijker of verwarrend.

Van begrippen die je niet kent, zou je de betekenis eventueel op kunnen zoeken op de volgende plaatsen op het Internet:

http://www.furore.nl/iw001329.htm http://www.casema.net/~tbosgaar/faq/wrdlst/ http://home.wish.net/~ruudvol/faqb.htm http://www.internetcollege.nl/vakken/informatiekunde/indexned.html

(en er zijn ongetwijfeld nog veel meer van dergelijke sites, zou je me alsjeblieft de url door willen geven, als je een goede site hebt gevonden, zodat andere Linux-gebruikers daar ook plezier van kunnen hebben?)

Er wordt bij het vertalen niet altijd acht geslagen op de inhoud van het document, in die zin of de daarin genoemde setup nog wel werkt met de huidige kernel of programma's. Wanneer door de vertalers ook nog die stap zou moeten worden genomen, dus het testen, zou het veel te lang gaan duren eer alle documenten zijn vertaald. Mocht je erachter komen dat er verouderde informatie in een vertaald document staat, dan heb je in ieder geval de volgende keuzes:

• Jammer, maar helaas, er is geen bijgewerkte info in 't Nederlands voor wat je wilt;

• Je gaat zoeken naar andere documentatie op Internet over hetzelfde onderwerp;

• Je probeert de oorspronkelijke auteur over te halen het document bij te werken (dus niet de vertaler, die vertaalt slechts zo goed mogelijk wat in het oorspronkelijke document beschreven staat);

• Je gaat het zelf proberen;

• Je koopt een goed boek waarin de door jou gewenste informatie duidelijk wordt beschreven;

• Je leest anderstalige informatie die wel is bijgewerkt;

• Je zoekt hulp in een forum of één van de nieuwsgroepen.

In geen geval is het de bedoeling dat je, hoe vriendelijk ook bedoeld, de vertalers wijst op verouderde of onjuiste informatie, tenzij het vertaalfouten betreft. Dit geldt uiteraard niet voor hele kleine foutjes zoals een beschreven onjuiste optie want deze wordt dan vaak ook al in een later stadium door de auteur opgemerkt of aan de auteur doorgegeven door degene die het document vertaalt. Ook al kan een document dan verouderd zijn, soms kan het je nog op weg helpen, door je in ieder geval bekend te maken met gebruikte termen en mogelijkheden met betrekking tot het gekozen onderwerp. Uiteraard wordt het door de Linux-gemeenschap bijzonder op prijs gesteld als je op zo'n moment je editor voor de dag haalt en aantekeningen maakt van al hetgeen je tegen bent gekomen op je speurtocht naar de juiste configuratie en deze op een goed bereikbare plek op Internet plaatst, zodat ook anderen er plezier van kunnen hebben. En ja, die lokatie kan ook de site NL.linux.org zijn als je daar prijs op stelt en het om goed leesbare documentatie gaat. Meer hierover vind je in andere hoofdstukken in dit document.

Van documenten die niet direct op deze site zijn geplaatst is een verwijzing opgenomen in een database die op nl.linux.org draait. Met gebruik van de gegevens in deze database wordt een index gegenereerd. In deze index vind je tevens de Nederlandse Linux documentatie INDEX, hierna te noemen NL-INDEX; een index met verwijzingen naar Nederlandstalige documentatie van de volgende sites:

http://doc.nllgg.nl, http://linux-nl.cx, http://nl.linux.org en andere bekende documenten van een aantal kleinere sites.

Bookmark deze site alsjeblieft en niet de vele anderen waar helaas vanwege het kopiëren in plaats van linken naar de documenten of mirroren van dit deel van de site maar al te vaak nog verouderde vertalingen zijn te vinden. De meest recente documenten vind je dus terug via de url's: Nederlandstalige Documentatie pagina en Nederlandse Linux documentatie INDEX en mirrors van beide lokaties.

Laatste versies

Er gaat vaak wat tijd overeen eer een document op een algemeen toegankelijke site, zoals de hierboven genoemden, wordt geplaatst, intussen kan het nieuwe document soms wel al via het Internet worden bekeken. Meestal staat de url hiervan in het document zelf. Voor wat betreft de Nederlandstalige documenten zal een dergelijk document natuurlijk altijd later verschijnen dan het oorspronkelijke document. Bovendien is er nog altijd een inhaalslag te doen, dus heb je helaas regelmatig met een oudere versie te maken. Wel wordt zoveel mogelijk in de gaten gehouden dat de belangrijkste documenten zo snel mogelijk worden bijgewerkt.

Downloaden van Nederlandstalige documentatie

De documenten die op http://doc.nl.linux.org/HOWTO/, http://doc.nl.linux.org/GUIDE/, http://doc.nl.linux.org/INFOPAGE/, http://doc.nl.linux.org/MANPAGE/ en, http://doc.nl.linux.org/MISC/ worden weergegeven, kunnen direct worden gedownload vanaf respectievelijk: ftp.nl.linux.org/pub/HOWTO, ftp.nl.linux.org/pub/GUIDE, ftp.nl.linux.org/pub/INFOPAGE, ftp.nl.linux.org/pub/MANPAGE en ftp.nl.linux.org/pub/MISC.

Inloggen als "anonymous", wachtwoord is je email-adres.

Let op! Het gaat hier dus niet om alle documenten die in de gezamenlijke NL-INDEX van Jan-Willem Smaal staan vermeld, want daarin zijn ook documenten opgenomen die niet lokaal op nl.linux.org zijn opgeslagen.

De documenten in de HOWTO-sectie zijn ook beschikbaar bij het Linux Documentatie Project wat tevens betekent dat ze op verschillende distributie-CD-ROM's terechtkomen. Het kan dus goed zijn dat de diverse documenten reeds op je harde schijf zijn geïnstalleerd.

Op dit moment worden de volgende bestandsformaten aangeboden:

Builders van het nl.linux.org-team

Om op plezierige wijze met meerdere mensen aan de verschillende documenten te kunnen werken, maken we bij nl.linux.org gebruik van CVS. CVS is een systeem waarbij het mogelijk is een (werk)kopie van de bestanden naar je lokale systeem over te halen om ze op je lokale harddisk te bewerken. Deze bestanden zijn onder het beheer van een package (CVS) geplaatst, waardoor je de mogelijkheid hebt offline aan de documenten te werken. De opslagplaats (repository genaamd, welke gewoon bestaat uit één of meer (sub)-directory's) bevindt zich op de server en de bestanden in deze (sub-)directory('s) worden vanaf je eigen werkkopie bijgewerkt als je de daarvoor van toepassing zijnde CVS-opdrachten geeft (bij geen continue verbinding nadat je een verbinding gemaakt hebt met de server via een Internet-verbinding). Een (sub-)directorystructuur in deze repository wordt een module genoemd (dit is dus een deel van het geheel). Iedere module heeft een naam toegewezen gekregen die niet noodzakelijkerwijs gelijk hoeft te zijn aan de naam van de betreffende (sub-)directory('s) waarin de van toepassing zijnde bestanden zijn opgeslagen. Door middel van een CVS-opdracht met als argument de naam van de opgegeven module heb je dus de mogelijkheid slechts aan een deel van de site mee te werken.

Reeds bestaande documenten

Als je fouten (typo's, niet werkende hyperlinks, onjuiste vertalingen e.d) tegenkomt in de documenten dan wordt het bijzonder gewaardeerd als je dit meldt bij de betreffende auteur/vertaler. In de meeste gevallen vind je het betreffende e-mailadres bovenaan het document. Houd alsjeblieft in de gaten dat het gezien de copyrights waaronder een document valt, voor een vertaler niet mogelijk is om de inhoud van een document radicaal te gaan veranderen. Aan een vertaler is het dus verstandiger om alleen typfoutjes, of andere fouten die te maken hebben met de Nederlandse taal door te geven. Voor overige voorkomende fouten/opmerkingen/suggesties kun je dan contact opnemen met de auteur. Voor de vertaalde documenten geldt ook hier dat je bericht in dat geval dan vaak in de Engelse taal zal moeten zijn.

Zelfgeschreven Nederlandstalige documenten

Als je dit wilt, kun je bijdragen aanleveren via email. Neem in dat geval alsjeblieft even contact op met de auteur van deze HOWTO, via [email protected] of één van de overige builders van nl.linux.org via [email protected] of direct met het documentatieteam bereikbaar via [email protected]. Lever je documentatie bijvoorkeur aan in SGML-formaat volgens de linuxdoc of DocBook DTD, of XML volgens de DocBook DTD of als je dit om wat voor reden dan ook niet kunt, in ASCII-formaat of HTML-formaat en lever dan de extra gegevens aan, zover deze nog niet in je document staan vermeld zoals eerder beschreven. Lever meerdere bronbestanden alsjeblieft aan in een tar-archief, bijvoorkeur gecomprimeerd met gzip. Het is namelijk niet altijd mogelijk er direct mee aan de slag te gaan en in dat geval is het makkelijker als slechts een enkel bestand wordt aangeleverd zodat niet een deel van de gegevens zoek kan raken. Een voordeel van het aanleveren van de door jou geschreven documentatie is dat deze zo mogelijk zal moeten omgezet in verschillende formaten en behalve op de officiële Linux Documentatie website en ftpsite ook beschikbaar zal komen op de cd-roms van de grotere distributies.

Een aangeleverd ASCII-document wordt naar wens omgezet in SGML of XML. Bij het aanleveren van een bijgewerkte versie door de auteur wordt dan wel verondersteld dat je de eerder aangemaakte sgml-versie hebt aangepast. De omzetting is dus éénmalig, bij een update van je document wordt verondersteld dat je je minimaal de beginselen van SGML of XML hebt eigengemaakt en dus zelf in staat bent om het document in SGML of XML bij te werken. Aangeleverde documenten zullen zo mogelijk tevens voor download en in diverse formaten beschikbaar worden gesteld. Spelfouten die tijdens deze omzetting worden geconstateerd zullen zo mogelijk worden gecorrigeerd. Als auteur/vertaler ben je er zelf verantwoordelijk voor dat de nieuwste versie van je document op de site staat. Uiteraard worden doorgegeven nieuwe versies zo snel mogelijk geplaatst.

Advies: vergeet het copyright niet in geval van een zelfgeschreven document!

Denk er alsjeblieft goed over na als je van plan bent documentatie in HTML-formaat te schrijven, aangezien dit heel lastig is bij te werken. Om namelijk zover als maar mogelijk is HTML-compliant te zijn, maken we geen gebruik van speciale programma's om HTML/SGML documenten aan te maken, maar doen dit met de hand in een editor, ter voorkoming van rommelige en overbodige codes die kant-en-klare programma's vaak in het bestand plaatsen. Een bestand éénmalig voor je omzetten naar SGML of XML is niet zo'n probleem, je loopt echter het risico dat je op weerstand stuit als je hetzelfde document maar dan bijgewerkt in een ander dan het SGML-of XML-formaat aanlevert, wat voor de tweede keer naar SGML moet worden omgezet.

SGML-en XML-documenten kunnen tenminste nog op behoorlijke wijze worden omgezet naar andere formaten, wat helaas niet evenzo voor HTML-documenten geldt. Wil je het document dat je hebt geproduceerd later nog eens bijwerken, dan is het heel lastig als je slechts een HTML document als bronbestand hebt. Het zou jammer zijn van al je werk, als het nadat het klaar is, toch nog gewenst is als het in meerdere/andere formaten verschijnt. Bovendien is het makkelijker om bijvoorbeeld een ASCII-bestand zonder overbodige codes om te zetten naar SGML dan een HTML-bestand waarin dus al flink wat codes staan, die moeten dan immers allemaal worden verwijderd.

Beginners denken vaak dat zij nog niet voldoende weten om een document te kunnen schrijven of schrikken misschien terug van de vele termen waarmee een Linux-goeroe zo af en toe eens strooit, maar willen eigenlijk wel graag een bijdrage leveren. Als je tot deze groep behoort, maak je dan geen zorgen om onkunde over SGML, CVS of welke termen hier in deze HOWTO dan ook genoemd zijn, waar je nog niet bekend mee bent: Ook hulp van beginners is heel welkom. We zouden op nl.linux.org ook graag documenten zien met meer afbeeldingen die een beginner juist op weg kunnen helpen of die gebruikers die zich liever met de grafische omgeving onder Linux bezighouden. Dus als je iets gelukt is om te configureren, bereid bent het in de vorm van documentatie te gieten omdat je denkt dat het van nut kan zijn voor andere (beginnende) gebruikers, laat ons dit dan alsjeblieft weten zodat we of een link op de site kunnen plaatsen naar je eigen homepage of je bijdrage aan de Linux-gemeenschap wellicht ergens op de site kunnen plaatsen. De auteur is altijd bereid om je op weg te helpen als je jezelf de beginselen van CVS en eventueel SGML eigen wilt maken om mee te kunnen werken aan de (documentatiesectie van de) site.

Proeflezers

Als je voordat de documenten in de index zullen worden geplaatst, bereid bent om als proeflezer te fungeren, zou ik het prettig vinden als je een berichtje bij me achterliet. De bedoeling hiervan is om van te voren zoveel mogelijk typfoutjes om niet lekker lopende zinnen eruit te halen. Enige kennis van de Nederlandse taal (en bijvoorkeur ook de Engelse taal) is dan dus zeer welkom!

Benodigde faciliteiten, zoals het hiervoor besproken CVS, waarvoor je een account nodig hebt, en de inschrijving op een daarvoor bestemde mailinglist, kun je aanvragen via [email protected]. Ook beginnende Linux-gebruikers die liever (nog) onder Windows meehelpen, heten wij van harte welkom. Voor die mensen is er WinCVS, een naar Windows geporte versie van CVS.

Schroom alsjeblieft niet contact op te nemen met de auteur van dit document als je (nog) niet bekend bent met WinCVS/CVS en er alleen met de beschikbare documentatie niet uitkomt.

HOWTO copyright

Tenzij anders aangegeven, vallen HOWTO-documenten onder het copyright van hun respectieve auteurs. Linux HOWTO documenten mogen geheel of gedeeltelijk worden gereproduceerd en gedistribueerd, via elk fysiek of elektronisch medium, zolang deze copyright-melding op alle kopieën behouden blijft. Commerciële herdistributie is toegestaan en wordt aangemoedigd; de auteur zou echter graag van dergelijk distributies op de hoogte worden gebracht.

Alle vertalingen, afgeleide werken, of verzamelde werken aangaande enige Linux HOWTO-documenten moeten zijn voorzien van deze copyright-melding. Dat wil zeggen dat je geen afgeleide werken van een HOWTO mag produceren en aanvullende beperkingen op de distributie ervan mag opleggen. Uitzonderingen op deze regels kunnen onder bepaalde voorwaarden worden toegestaan; neem alsjeblieft contact op met de Linux HOWTO coördinator via het hieronder aangegeven adres.

In 't kort, we willen verspreiding van deze informatie via zoveel mogelijk kanalen bevorderen. We willen echter dat het copyright op de HOWTO-documenten behouden blijft, en zouden graag op de hoogte worden gesteld van alle plannen om de HOWTO's te herdistribueren.

Als je vragen hebt, neem dan alsjeblieft contact op met Greg Hankins, de Linux HOWTO coördinator, via email [email protected].