De Documentatie-HOWTO-NL

Ellen Bokhorst, bokkie@nl.linux.org

In dit document wordt algemene informatie gegeven over de Nederlandstalige documentatie voor onder Linux. Tevens tref je hierin aanwijzigingen op welke wijze je een bijdrage zou kunnen leveren aan Nederlandstalige Linux Documentatie.

Inhoudsopgave

1. Nederlandstalige Linux Documentatie..................................................................................................................1 2. HOWTO’s ............................................................................................................................................................1 3. GUIDE’S ..............................................................................................................................................................3 4. Infopages ..............................................................................................................................................................3 5. Algemene informatie.............................................................................................................................................4 6. Bijdragen..............................................................................................................................................................7 7. SGML-tools ........................................................................................................................................................ 10 8. Copyrights .......................................................................................................................................................... 10 9. Erkenningen........................................................................................................................................................ 11

1. Nederlandstalige Linux Documentatie

Sinds begin 1999 wordt op NL.linux.org gewerkt aan Linux Documentatie voor de Nederlandstalige Linux gebruikers. In de documentatiesectie van NL.linux.org vind je thans de volgende mogelijke soorten documentatie:

• HOWTO’s

• GUIDE’s

• Infopages

• Manpages

• FAQ’s/VVV’s

2. HOWTO’s

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

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

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

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

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

3. GUIDE’S

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

3.2. 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 (http://www.google.com) 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 (http://www.tldp.org/LDP/lame/LAME/linux-admin-made-easy/index.html) Linux Installation and Getting Started (http://www.tldp.org/LDP/gs/gs.html) The CVS Book, Open Source Development with CVS (http://cvsbook.red-bean.com/) Beginner’s Guide to CGI Scripting with Perl (http://www.lics.com/begperl/index.html) Hoofdstuk 20 van het boek: Computer Science and Perl Programming (http://www.oreilly.com/catalog/tpj1/chapter/index.html) MH & nmh: Email for Users & Programmers (http://www.ics.uci.edu/~mh/book/) Advanced Linux Programming (http://www.advancedlinuxprogramming.com/downloads.html) GTK+ / Gnome Application Development (http://developer.gnome.org/doc/GGAD/ggad.html) Linux Device Drivers, 2nd Edition (http://www.xml.com/ldd/chapter/book/) The GNU Awk User’s Guide (http://www.gnu.org/manual/gawk-3.1.1/html-mono/gawk.html) GNU Autoconf, Automake, and Libtool (http://sources.redhat.com/autobook/autobook_toc.html)

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 (http://ftp.nl.linux.org/pub/GUIDE)

4. Infopages

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

5. Algemene informatie

5.1. 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 (http://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 (http://doc.nl.linux.org/nldocs/index.html), hierna te noemen NL-INDEX; een index met verwijzingen naar Nederlandstalige documentatie van de volgende sites:

http://doc.nllgg.nl (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 (http://doc.nl.linux.org/) pagina en Nederlandse Linux documentatie INDEX (http://doc.nl.linux.org/nldocs/index.html) en mirrors van beide lokaties.

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

5.3. 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 (http://ftp.nl.linux.org/pub/HOWTO/), ftp.nl.linux.org/pub/GUIDE (http://ftp.nl.linux.org/pub/GUIDE/), ftp.nl.linux.org/pub/INFOPAGE (http://ftp.nl.linux.org/pub/INFOPAGE/), ftp.nl.linux.org/pub/MANPAGE (http://ftp.nl.linux.org/pub/MANPAGE/) en ftp.nl.linux.org/pub/MISC (http://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 (http://www.tldp.org) 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:

5.3.1. SGML, XML , enz.

Te vinden in een subdirectory genaamd source, zoals bijvoorbeeld in: ftp.nl.linux.org/pub/HOWTO/source/ Hierin tref je archiefbestanden aan met als inhoud het broncodebestand of meerdere broncodebestanden van waaruit de diverse andere formaten worden aangemaakt. Meestal gaat het hier bijvoorbeeld om bestanden met de extensie .sgml, .xml, .tex, of .texi. In een source-archief zijn tevens eventuele afbeeldingen en/of scripts aangeleverd door de auteur van het document te vinden.

5.3.2. ASCII-tekst

Te vinden in de root van één van de subdirectory’s, zoals bijvoorbeeld: ftp.nl.linux.org/pub/HOWTO/ Dit document kan onder ieder willekeurig OS worden bekeken. Onder Linux kun je hiervoor bijvoorbeeld de opdracht less gebruiken. Voor bijvoorbeeld het bekijken van de Colour-ls-NL geef je achter de prompt de volgende opdracht:

less Colour-ls-NL

Onder DOS, Windows, OS/2 of enig ander OS, kun je een editor, willekeurige tekstverwerker of browser gebruiken.

5.3.3. HTML

Te vinden in een subdirectory html, zoals bijvoorbeeld: ftp.nl.linux.org/pub/HOWTO/html/

Bij het omzetten van een sgml-bestand wordt het bestand in meerdere html-bestanden gesplitst. Deze htmlbestanden zijn voor het downloaden in een tar-archief verpakt tot één bestand en vervolgens met het commando gzip gecomprimeerd. Uitpakken en decomprimeren gaat als volgt:

tar -xvzf foo.tar.gz

Dus als je het tar-archief met de DOS-Win-to-Linux-NL wilt uitpakken, geef je de volgende opdracht:

tar xvzf DOS-Win-to-Linux-NL.html.tar.gz

Vervolgens zullen de diverse html-bestanden worden uitgepakt. Je kunt ze bekijken met iedere willekeurige browser. In dit archiefbestand zijn tevens eventuele afbeeldingen en/of scripts aangeleverd door de auteur van het document te vinden.

Je kunt de html-bestanden ook niet getarred en gezipt downloaden, als één enkel html-bestand. Deze zijn te vinden in een subdirectory met de naam onehtml, zoals bijvoorbeeld in: ftp.nl.linux.org/pub/HOWTO/onehtml/. Nadeel ten opzichte van het html-archief of sgml-archief is dat je dan niet direct de beschikking hebt over eventueel door de auteur beschikbare afbeeldingen en/of scripts.

De Documentatie-HOWTO-NL

5.3.4. PS Te vinden in een subdirectory met de naam ps, zoals in: ftp.nl.linux.org/pub/HOWTO/ps/ Bestanden eindigend op ‘ps’ zijn PostScript bestanden die onder X kunnen worden bekeken met bijvoorbeeld gs. Gebruikers van Windows die deze bestandsformaten onder Windows willen lezen, kunnen hiervoor de previewer gv.zip downloaden vanaf: http://www.phys.uu.nl/~astbc/bekijkers/ghostview.html Op deze pagina is tevens een korte beschrijving te vinden over hoe je deze previewer kunt installeren. Je hebt hiervoor wel een utility nodig om bestanden met een .zip-extensie uit te kunnen pakken, zoals bijvoorbeeld unzip.exe of winzip.exe.

5.3.5. PDF Te vinden in een subdirectory met de naam pdf, zoals in: ftp.nl.linux.org/pub/HOWTO/pdf/ Bestanden eindigend op ‘pdf’ zijn bestanden die bijvoorbeeld kunnen worden gelezen met de Acrobat Reader, beschikbaar voor verschillende platformen.

6. Bijdragen

Bijdragen met betrekking tot Nederlandstalige Linux-Documentatie zijn van harte welkom. Als je een auteur, vertaler of website-builder een bijdrage wilt sturen, hetzij door het leveren van kritiek, aanvullingen en/of opmerkingen enz., stuur deze dan naar nldoc@nl.linux.org of builders@nl.linux.org voor de Nederlandstalige versies en naar de oorspronkelijke auteur die bovenaan het document staat genoemd voor de anderstalige documenten. Houd je in alle gevallen alsjeblieft aan de netiquette. Als je deze niet kent, lees dan eerst de http://nl.linux.org/doc/HOWTO/Quoting-HOWTO-NL eens door, alvorens je iets post in de nieuwsgroepen of mail stuurt naar één van de auteurs, vertalers of websitebuilders. Nogmaals, je hebt te maken met vrijwilligers die hun vrije tijd geven om je te kunnen helpen. (en uiteraard ook om er van elkaar meer van te leren;-)) Om je bijdrage in onze DATABASE te verwerken, als een link naar je homepage of als document dat bij nl.linux.org wordt aangeleverd en dus ook voor download en meestal in diverse formaten beschikbaar zal zijn, hebben we de volgende informatie nodig:

• Titel van het document;

• Naam van de auteur;

• Naam van de vertaler;

• Versienummer;

• Datum;

• De url (bv doc.nl.linux.org/HOWTO of de URL naar je homepage);

• Korte samenvattting van de inhoud van het document;

• Het e-mailadres van de auteur;

• Het e-mailadres van de vertaler;

• Documentatiesoort (HOWTO, FAQ/VVV, artikel, webpagina, handleiding, tutorial of boek);

• Categorie waarin het document thuishoort:

  |  1 | algemeen           | Algemene documenten (niet Linux specifiek)
  |  2 | distributies       | Distributie specifieke documenten.

  |  3 | document structuur | LinuxDoc/DocBook DTD SGML, LaTeX e.d.
  |  4 | emulator           | Dosemu, Wine etc..
  |  5 | kernel             | Kernel (compilen, kerneld, modprobe etc...)
  |  6 | netwerk            | Netwerken en het configureren van netwerk services
  |  7 | installatie        | Installatie van Linux (naast andere Operating Syst
  |  8 | ISP                | Het configureren van Linux voor bepaalde Internet
  |  9 | spellen            | Games, configuratie installatie tips etc..
  | 10 | configuratie       | Algemene configuratie documenten.
  | 11 | mail               | Mail configuratie (sendmail + m4, procmail, exim e
  | 12 | news               | Newsconfiguratie.
  | 13 | X Window System    | Over het X Window systeem (X11)
  | 14 | systeem            | systeemtaken zoals diskquota,printen hardware inst
  | 15 | geluid             | Soundcards, MIDI e.d.
  | 16 | applicaties        | Over verschillende Unix applicaties
  | 17 | beginners          | Informatie voor beginnende gebruikers
  | 18 | programmeren       | Programmeren onder Linux

• Als laatste kun je ook wat trefwoorden opgeven, wat gebruikers mogelijk in zouden kunnen tikken als zoekargument wanneer ze op zoek zijn naar bepaalde informatie.

Vooral voor categorie nr. 17 kunnen we nog wel wat documentatie gebruiken;-) Leuk zou zijn als hier ook wat meer stap voor stap handleidingen voor zouden zijn voorzien van afbeeldingen.

Het zou prettig zijn als je deze informatie zelf aan kunt leveren, aangezien dat de builders tijd scheelt bij het verwerken van de gegevens. Alle informatie is dus niet noodzakelijk, we stellen het gewoon op prijs als je de van toepassing zijnde gegevens gewoon zelf aanlevert. Wil je echt actief mee doen met het team van nl.linux.org en/of met een aantal mensen samenwerken aan een deel van de site, stuur dan alsjeblieft een mailtje naar builders@nl.linux.org voor een CVS-account en geef daarin aan waar je graag aan mee wilt werken of misschien zelfs wel leuke ideeën hebt voor de site.

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

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

6.3. 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 bokkie@nl.linux.org of één van de overige builders van nl.linux.org via builders@nl.linux.org of direct met het documentatieteam bereikbaar via nldoc@nl.linux.org. 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.

6.4. 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 builders@nl.linux.org. 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.

7. SGML-tools

SGML staat voor Standard Generalised Markup Language en wordt in het algemeen gebruikt voor het aanmaken van HOWTO-documenten.

Meer Nederlandstalige informatie is in ieder geval te vinden in de volgende documenten:

De SGML tutorial voor LinuxDoc DTD van Luc Janssen en de SGML-Tools voor het NLLDP van Hugo van der Kooy op http://doc.nllgg.nl (http://doc.nllgg.nl/), de http://nl.linux.org/doc/HOWTO/LinuxDoc+Emacs+Ispell-HOWTO-NL.html de DocBook-Install-NL (http://nl.linux.org/doc/HOWTO/DocBook-Install-NL/article.html) waarin wordt beschreven hoe een DocBook systeem kan worden opgezet,

Bovenaan ieder source-document zie je een documenttype staan, dit zijn over het algemeen óf de linuxdoc óf DocBook types.

Voor het converteren van het type linuxdoc is het package sgml-tools 1.x nodig om de documenten om te zetten naar andere formaten. Voor het type DocBook is het package sgmltools 2.x nodig. Beide packages in rpm-formaat kunnen als volgt op hetzelfde Linux-systeem worden geïnstalleerd:

rpm -ivh sgml-tools*.rpm
rpm -ivh --replacefiles sgmltools*.rpm
/usr/bin/gensgmlenv

Je kunt een document van het type linuxdoc als volgt converteren naar DocBook:

jade -t sgml -d '/usr/share/sgml/stylesheets/sgmltools/ld2db.dsl#db'\
foo.sgml > foo.db

Hierbij is uitgegaan van een RedHat 6.1 of Mandrake 7.0/7.1 systeem, mogelijk dat het bestand ld2db.dsl ergens anders op je harddisk staat; pas zonodig het voorafgaande directorypad aan. Het is goed mogelijk dat je bij conversie aardig wat foutmeldingen krijgt omdat de auteur in de linuxdoc versies verzuimd heeft eindtags te gebruiken.

8. Copyrights

Documentatie valt onder copyright. Wat dit copyright inhoudt, verschilt nogal eens. Een copyright dient over het algemeen om de auteur/vertaler te beschermen. Ga er in ieder geval maar vanuit dat je zelf verantwoordelijk bent voor wat je doet. Dat wil zeggen dat wanneer je aanwijzingen in een document opvolgt de auteur/vertaler niet aansprakelijk kunt stellen worden voor als er iets helemaal mis gaat met je systeem(onderdelen) e.d., er iets door beschadigt (zeer onwaarschijnlijk, maar voor het geval dat). De copyright-vermelding die een auteur hanteert, vind je terug in het document zelf. In de hieropvolgende sectie heb ik de vertaling opgenomen van het algemene copyright van de HOWTO-documenten, dit is echter geen officiële versie.

De officiële versie is te vinden in http://nl.linux.org/copyright/. Als je daar het betreffende copyright niet kunt vinden, kijk dan eens bij http://www.gnu.org of je het daar misschien ergens aantreft of tik de naam van het copyright in bij een zoekmachine. Bij de vertalingen die op http://nl.linux.org/ terechtkomen wordt het oorspronkelijke copyright gehanteerd, wellicht vind je het in een vertaalde versie of de originele tekst. Hoe dan ook, ten alle tijde is het originele copyright van toepassing, tenzij de auteur (niet de vertaler) nadrukkelijk anders vereist. Dit betekent dat je je niet kunt beroepen op eventuele fouten die in de vertalingen van de copyrights zijn gemaakt. Dit klinkt misschien wat streng, maar is slechts bedoeld om zowel de oorspronkelijke auteur als de vertaler te beschermen. Auteurs willen wel behulpzaam zijn om je op weg te helpen, maar er uiteraard niet zelf de dupe van worden.

8.1. 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 gregh@sunsite.unc.edu.

9. Erkenningen

Begin 1999 begon ik in combinatie met een studie UNIX met het vertalen van Linux-HOWTO’s. Na het plaatsen van een aantal vertalingen op mijn home-page verhuisde deze documentatie al snel naar een centrale plaats zodat het voor de overige Linux-gebruikers gemakkelijker toegankelijker zou zijn en er gelegenheid zou zijn om de source en andere formaten voor download beschikbaar te stellen.

De hoeveelheid Nederlandstalige documenten is inmiddels zodanig gestegen, dat het niet eens meer mogelijk zou zijn deze informatie op één enkele home-page (van 5 Mb) te plaatsen, zeker niet als ik daarbij alle ruimte die de diverse formaten voor download in beslag nemen, meetel.

Behalve vertalingen tref je er nu ook zelf geschreven documenten aan zoals de Belgium-HOWTO van Dag Wieers, de Girotel-met-Wine-HOWTO van Jasper Aukes en de NL-INDEX van Jan-Willem Smaal van de builders van het documentatie-team van nl.linux.org en nog diverse andere bijdragen.

Hierbij wil ik Rik van Riel (riel@nl.linux.org) en Maarten van Steenbergen (steenbrg@nl.linux.org) bedanken voor het beschikbaar stellen van ruimte en het opzetten van een Nederlandstalige Linux-site met als primaire doel de reeds beschikbare documentatie te verzamelen.

Verder wil ik bij deze iedereen bedanken die tot nu toe zijn steentje heeft bijgedragen aan het proeflezen, aanleveren van correcties, mentale steun, aanleveren van eigen bijdragen, meehelpen met vertalen, aanleveren van de nieuwste versie van de source, geven van toestemming voor het vertalen, (hulp bij) het vervaardigen van scripts, enz, enz, enz....

De volgende mensen hebben hieraan reeds een bijdrage geleverd:

Jan-Willem Smaal; Maarten van Steenbergen; Rik van Riel; Jasper Aukes; Dag Wieers; Ramses van Pinxteren; Gerrit Holl; Chris Fischer; Eric S. Raymond; Guido Gonzato; Remco vd Noord; Andries Brouwer; Gebruikers in de nieuwsgroepen nl.comp.os.linux en nl.comp.os.linux.discussie; M’n woordenboeken en computer-encyclopedie;-), en verder iedereen die ik vergeten ben.

Ik wens een ieder veel leesplezier!