<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
$FreeBSDde$
basiert auf: r38854
-->
<chapter id="overview">
<title>�berblick</title>
<para>Herzlich Willkommen beim FreeBSD-Dokumentationsprojekt.
Qualitativ hochwertige Dokumentation ist ein wichtiger
Erfolgsfaktor und sehr bedeutend f�r die Verbreitung von
FreeBSD. Die wichtigste Quelle daf�r ist das
FreeBSD-Dokumentationsprojekt (FDP). Jeder Beitrag, der zu diesem
Projekt geleistet wird, ist ungemein wertvoll.</para>
<para>Es ist das Anliegen dieser Fibel, den Leser mit dem FDP
vertraut zu machen und zu erkl�ren, <emphasis>wie das FDP
organisiert ist</emphasis>, <emphasis>wie man selber Dokumente
erstellt und an das FDP einreicht</emphasis> und <emphasis>wie
die verf�gbaren Werkzeuge effektiv beim Schreiben
eingesetzt werden k�nnen</emphasis>.</para>
<indexterm>
<primary>Mitgliedschaft</primary>
</indexterm>
<para>Wie jedes Opensourceprojekt, ist auch das FDP auf die Mithilfe
vieler angewiesen. Deshalb ist jeder herzlich eingeladen
mitzuarbeiten. Die daf�r erforderlichen Voraussetzungen sind
gering und es gibt keine Verpflichtung eine bestimmte Menge an
Dokumenten pro Monat oder Jahr beizusteuern. Das Einzige, was Sie
tun m�ssen, ist sich auf der Mailingliste &a.doc; einzutragen.</para>
<para>Nach dem Lesen der FDP-Fibel sollte man wissen:</para>
<itemizedlist>
<listitem>
<para>welche Dokumente durch das FDP betreut werden,</para>
</listitem>
<listitem>
<para>wie man SGML-Dokumente liest und den SGML-Quellcode der
durch das FDP betreuten Dokumente versteht,</para>
</listitem>
<listitem>
<para>wie man selbst �nderungen an Dokumenten vornehmen
kann und</para>
</listitem>
<listitem>
<para>wie man �nderungen zur Begutachtung durch das FDP
einreichen kann.</para>
</listitem>
</itemizedlist>
<sect1 id="overview-doc">
<title>Die FreeBSD-Dokumentationsreihe</title>
<para>Das FDP umfa�t vier verschiedene Kategorien:</para>
<variablelist>
<varlistentry>
<term>Manualpages</term>
<listitem>
<para>Die englischen Manualpages wurden nicht vom FDP
geschrieben, da sie ein Teil des Basissystems sind. Jedoch
k�nnen bzw. wurden bereits Teile von existierenden
Manualpages umformuliert, um sie verst�ndlicher zu
machen oder um Fehler zu beheben.</para>
<para>F�r die �bersetzung der Manualpages des
Systems in die verschiedenen Sprachen sind die einzelnen
�bersetzergruppen verantwortlich. Alle dabei
entstandenen �bersetzungen geh�ren zum
FDP.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Die FAQ</term>
<listitem>
<para>Das Ziel der FAQ ist es, Fragen, die auf den
verschiedenen Maillinglisten und in Newsgruppen
regelm��ig diskutiert werden, nach einem
einfachen Frage- und Antwort-Muster zu behandeln. Das
schlie�t nicht aus, das auf bestimmte Fragen
ausf�hrlich und umfassend eingegangen wird.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Das Handbuch</term>
<listitem>
<para>Das Ziel des Handbuches ist es, die
umfassende Quelle und Referenz im Netz f�r
FreeBSD-Benutzer zu sein.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Die Webseite</term>
<listitem>
<para>Die Webseite <ulink
url="&url.base;/index.html">http://www.FreeBSD.org</ulink>
und ihre vielen Spiegel auf der ganzen Welt vertreten das
FreeBSD-Projekt im WWW. F�r viele Menschen
ist sie der erste Kontakt mit FreeBSD.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Die Quellen f�r die FreeBSD-Website, das &os; Handbuch
sowie die &os; FAQ werden im <literal>doc/</literal>
Subversion-Repository von &os; verwaltet, das Sie �ber
<literal>svn://svn.FreeBSD.org/doc/</literal> erreichen
k�nnen.</para>
<para>Manualpages werden im <literal>src/</literal>
Subversion-Repository von &os; verwaltet, das Sie �ber
<literal>svn://svn.FreeBSD.org/base/</literal> erreichen
k�nnen.</para>
<para>Das bedeutet, dass alle �nderungen an den
Dateien f�r jeden verf�gbar sind und sich jeder
mit <application>svn</application> eine lokale Kopie der
Dokumentation anlegen kann.</para>
<para>Parallel zum FDP haben viele Menschen Anleitungen
geschrieben und Webseiten mit Bezug zu FreeBSD erstellt. Einige
davon werden im Subversion-Archiv verwaltet, sofern der Autor dem
zugestimmt hat. In anderen F�llen hat sich der Autor
entschlossen, seine Dokumentation au�erhalb des zentralen
FreeBSD-Archivs zu verwalten. Das FDP bem�ht sich, so
viele Verweise wie m�glich auf solche Quellen
bereitzustellen.</para>
</sect1>
<sect1 id="overview-before">
<title>Bevor es losgeht</title>
<para>Zum Verst�ndnis der folgenden Kapitel sollte folgendes
bereits bekannt sein:</para>
<itemizedlist>
<listitem>
<para>Wie eine aktuelle lokale Kopie des FreeBSD
Subversion-Repository mit Hilfe von
<application>svn</application> angelegt und gepflegt
werden kann.</para>
</listitem>
<listitem>
<para>Wie neue Programme mit Hilfe des
FreeBSD-Portsystems oder mittels &man.pkg.add.1;
heruntergeladen und installiert werden.</para>
</listitem>
</itemizedlist>
</sect1>
<sect1 id="overview-quick-start">
<title>Der Schnellstart</title>
<para>Falls man einfach loslegen m�chte und sich sicher genug
f�hlt, um alles weitere erst bei Bedarf nachzusehen, kann
man einfach den folgenden Anweisungen folgen:</para>
<procedure>
<step>
<para>Zuerst mu� der Metaport <filename
role="package">textproc/docproj</filename> auf dem
betreffenden Arbeitsrechner installiert werden.</para>
<screen>&prompt.root; <userinput>cd /usr/ports/textproc/docproj</userinput>
&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
</step>
<step>
<para>Laden Sie mit <application>svn</application> eine lokale
Kopie des FreeBSD-<filename>doc</filename>-Verzeichnisbaumes
herunter.</para>
<para>Selbst wenn Sie nur �ber eine geringe Bandbreite
oder wenig freien Plattenplatz verf�gen, m�ssen Sie
mindestens die Verzeichnisse <filename>head/share</filename>
sowie
<filename>head/<replaceable>language</replaceable>/share</filename>
auschecken, um an der Dokumentation arbeiten zu k�nnen.
Dazu ein Beispiel:</para>
<screen>&prompt.user; <userinput>mkdir -p head/share</userinput>
&prompt.user; <userinput>mkdir -p head/en_US.ISO8859-1/share</userinput>
&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/share head/share</userinput>
&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/share head/en_US.ISO8859-1/share</userinput></screen>
<para>F�r den Fall, dass ausreichend Platz auf der
Festplatte vorhanden ist, kann auch eine eine
vollst�ndige Arbeitskopie des gesamten Subversion-Baumes
anlegt werden.</para>
<screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head head</userinput></screen>
</step>
<step>
<para>Sollte geplant sein, ein existierendes Buch oder einen
existierenden Artikel zu �ndern, mu�
nat�rlich noch zus�tzlich das betreffende
Verzeichnis aus dem CVS-Archiv geholt werden. Soll hingegen
ein neues Buch oder ein neuer Artikel geschrieben werden,
empfiehlt es sich, auf bestehende B�cher und Artikel
zur�ckzugreifen und diese als Vorlage zu nutzen.</para>
<para>Ein Artikel �ber die Konfiguration eines VPNs
zwischen FreeBSD und Windows 2000 kann wie
folgt erstellt werden:</para>
<procedure>
<step>
<para>Zuerst wird das Verzeichnis
<filename>articles</filename> aus dem FreeBSD-CVS-Archiv
lokal angelegt:</para>
<screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/articles</userinput></screen>
</step>
<step>
<para>Anschlie�end kopiert man einen bereits
existierenden Artikel und nutzt ihn als Vorlage. In
diesem Beispiel soll der neue Artikel im Verzeichnis
<filename>vpn-w2k</filename> liegen:</para>
<screen>&prompt.user; <userinput>cd head/en_US.ISO8859-1/articles</userinput>
&prompt.user; <userinput>svn export committers-guide vpn-w2k</userinput></screen>
</step>
</procedure>
<para>Bereits exisitierende Dokumente, die ge�ndert
werden sollen, k�nnen direkt aus dem CVS-Archiv
geholt werden. Das folgende Beispiel zeigt das
f�r die FAQ aus dem Verzeichnis
<filename>head/en_US.ISO8859-1/books/faq</filename>:</para>
<screen>&prompt.user; <userinput>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.ISO8859-1/books/faq</userinput></screen>
</step>
<step>
<para>Jetzt k�nnen die <filename>.sgml</filename> Dateien
mit einem beliebigen Texteditor bearbeitet werden.</para>
</step>
<step>
<!--?
Vielleicht besser als Befehl auf der Kommandozeile
darstellen?
Oliver Fischer
-->
<para>Danach ist <command>make</command> mit dem Ziel
<maketarget>lint</maketarget> aufzurufen, um das gesamte
Dokument auf Auszeichnungsfehler hin zu untersuchen, ohne
dass zeitaufw�ndige Transformationen vorgenommen
werden.</para>
<screen>&prompt.user; <userinput>make lint</userinput></screen>
<!--?
Glossar sollte vorhanden sein. Darin dann erkl�ren,
was mit Ziel- und Quelldokument gemeint ist.
Oliver Fischer
-->
<para>Soll anschlie�end das Zieldokument erstellt
werden, kann mit Hilfe der Variable
<varname>FORMATS</varname> bestimmt werden, welche
Ausgabeformate erzeugt werden sollen. Unterst�tzt werden
momentan <literal>html</literal>,
<literal>html-split</literal>, <literal>txt</literal>,
<literal>ps</literal>, <literal>pdf</literal> und
<literal>rtf</literal>. Die aktuelle Liste der
unterst�tzten Formate befindet sich am Anfang der Datei
<filename>head/share/mk/doc.docbook.mk</filename>. Bei der
Verwendung dieser Variable ist es wichtig, darauf zu achten,
dass die Angabe der gew�nschten Formate in
Anf�hrungszeichen eingeschlossen wird, sofern mehr als
nur ein Format gleichzeitig erstellt werden soll.</para>
<para>Wenn das Dokument beispielsweise nach
<literal>HTML</literal> konvertiert werden soll, kann dies
so vorgenommen werden:</para>
<screen>&prompt.user; <userinput>make FORMATS=html</userinput></screen>
<para>Soll es hingegen in den Formaten <literal>html</literal>
und <literal>txt</literal> erzeugt werden,
kann man entweder
&man.make.1; zweimal hintereinander aufrufen:</para>
<screen>&prompt.user; <userinput>make FORMATS=html</userinput>
&prompt.user; <userinput>make FORMATS=txt</userinput></screen>
<para>oder beide Formate mit einem Aufruf von &man.make.1;
erzeugen:</para>
<screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen>
</step>
<step>
<para>Zum Schlu� m�ssen die �nderungen an das
FDP mittels &man.send-pr.1; eingesandt werden.</para>
</step>
</procedure>
</sect1>
</chapter>