347 lines
13 KiB
XML
347 lines
13 KiB
XML
<?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>
|