<!-- 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: de-docproj/books/fdp-primer/overview/chapter.sgml,v 1.7 2003/12/05 00:03:08 mheinen Exp $
     basiert auf: 1.19

-->

<chapter id="overview">
  <title>&Uuml;berblick</title>

  <para>Herzlich Willkommen beim FreeBSD-Dokumentationsprojekt.
    Qualitativ hochwertige Dokumentation ist ein wichtiger
    Erfolgsfaktor und sehr bedeutend f&uuml;r die Verbreitung von
    FreeBSD. Die wichtigste Quelle daf&uuml;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&auml;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&uuml;gbaren Werkzeuge effektiv beim Schreiben
      eingesetzt werden k&ouml;nnen</emphasis>.</para>

  <para>Wie jedes Opensourceprojekt, ist auch das FDP auf die Mithilfe
    vieler angewiesen. Deshalb ist jeder herzlich eingeladen
    mitzuarbeiten. Die daf&uuml;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&uuml;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 &Auml;nderungen an Dokumenten vornehmen
        kann und</para>
    </listitem>

    <listitem>
      <para>wie man &Auml;nderungen zur Begutachtung durch das FDP
        einreichen kann.</para>
    </listitem>
  </itemizedlist>

  <sect1 id="overview-doc">
    <title>Die FreeBSD-Dokumentationsreihe</title>

    <para>Das FDP umfa&szlig;t vier verschiedene Kategorien:</para>

    <variablelist>
      <varlistentry>
        <term>Hilfeseiten</term>

        <listitem>
          <para>Die englischen Hilfeseiten wurden nicht vom FDP
            geschrieben, da sie ein Teil des Basissystems sind. Jedoch
            k&ouml;nnen bzw. wurden bereits Teile von existierenden
            Hilfeseiten umformuliert, um sie verst&auml;ndlicher zu
            machen oder um Fehler zu beheben.</para>

          <para>F&uuml;r die &Uuml;bersetzung der Hilfeseiten des
            Systems in die verschiedenen Sprachen sind die einzelnen
            &Uuml;bersetzergruppen verantwortlich. Alle dabei
            entstandenen &Uuml;bersetzungen geh&ouml;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&auml;&szlig;ig diskutiert werden, nach einem
            einfachen  Frage- und Antwort-Muster zu behandeln. Das
            schlie&szlig;t nicht aus, das auf bestimmte Fragen
            ausf&uuml;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&uuml;r
            FreeBSD-Benutzer zu sein.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
         <term>Die Webseite</term>

         <listitem>
          <para>Die Webseite <ulink
              url="../../../../index.html">http://www.FreeBSD.org</ulink>
            und ihre vielen Spiegel auf der ganzen Welt vertreten das
            FreeBSD-Projekt im WWW. F&uuml;r viele Menschen
            ist sie der erste Kontakt mit FreeBSD.</para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>Jede dieser vier Kategorien wird im FreeBSD-CVS-Baum
      verwaltet. Das bedeutet, da&szlig; alle &Auml;nderungen an den
      Dateien f&uuml;r jeden verf&uuml;gbar sind und jeder sich
      mittels eines Programms wie <application>CVSup</application>
      oder <application>CTM</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 CVS-Archiv verwaltet, sofern der Autor dem
      zugestimmt hat. In anderen F&auml;llen hat sich der Autor
      entschlossen, seine Dokumentation au&szlig;erhalb des zentralen
      FreeBSD-CVS-Archivs zu verwalten. Das FDP bem&uuml;ht sich, so
      viele Verweise wie m&ouml;glich auf solche Quellen
      bereitzustellen.</para>
  </sect1>

  <sect1 id="overview-before">
    <title>Bevor es losgeht</title>

    <para>Zum Verst&auml;ndnis der folgenden Kapitel sollte folgendes
      bereits bekannt sein:</para>

    <itemizedlist>
      <listitem>
        <para>Wie eine aktuelle Kopie der FreeBSD-Dokumentation
          entweder auf Basis des FreeBSD-CVS-Archivs mittels
          <application>CVS</application>,
          <application>CTM</application> oder
          <application>CVSup</application> angelegt und gepflegt wird,
          oder wie mit <application>CVSup</application> eine frische
          Kopie des CVS-Archivs heruntergeladen wird.</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&ouml;chte und sich sicher genug
      f&uuml;hlt, um alles weitere erst bei Bedarf nachzusehen, kann
      man einfach den folgenden Anweisungen folgen:</para>

    <procedure>
      <step>
        <para>Zuerst mu&szlig; 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>Anschlie&szlig;end sollte eine lokale Kopie des
          FreeBSD-<filename>doc</filename>-Verzeichnisbaumes angelegt
          werden. Hierf&uuml;r kann man entweder auf
          <application>CVSup</application> im
          <literal>checkout</literal>-Modus zur&uuml;ckgreifen oder
          mittels <application>cvs</application> eine komplette Kopie
          des CVS-Archivs anlegen.</para>

        <para>Wenn man lieber mit einer Kopie des CVS-Archivs arbeiten
          m&ouml;chte, werden als Minimum die Verzeichnisse
          <filename>doc/share</filename> und
          <filename>doc/de_DE.ISO8859-1/share</filename>
          ben&ouml;tigt.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc/share</userinput>
&prompt.user; <userinput>cvs checkout doc/de_DE.ISO8859-1/share</userinput></screen>

        <para>F&uuml;r den Fall, da&szlig; ausreichend Platz auf der
          Festplatte vorhanden ist, kann auch eine eine
          vollst&auml;ndige Arbeitskopie des gesamten CVS-Baumes anlegt
          werden.</para>

	<screen>&prompt.user; <userinput>cvs checkout doc</userinput></screen>
      </step>

      <step>
        <para>Sollte geplant sein, ein existierendes Buch oder einen
          existierenden Artikel zu &auml;ndern, mu&szlig;
          nat&uuml;rlich noch zus&auml;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&uuml;cher und Artikel
          zur&uuml;ckzugreifen und diese als Vorlage zu nutzen.</para>

	<para>Ein Artikel &uuml;ber die Konfiguration eines VPNs
	  zwischen FreeBSD und Windows&nbsp;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>cvs checkout doc/de_DE.ISO8859-1/articles</userinput></screen>
	  </step>

	  <step>
            <para>Anschlie&szlig;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 doc/de_DE.ISO8859-1/articles</userinput>
&prompt.user; <userinput>cp -r committers-guide vpn-w2k</userinput></screen>
	  </step>
	</procedure>

	<para>Bereits exisitierende Dokumente, die ge&auml;ndert
	  werden sollen, k&ouml;nnen direkt aus dem CVS-Archiv
	  geholt werden.  Das folgende Beispiel zeigt das
	  f&uuml;r die FAQ aus dem Verzeichnis
          <filename>doc/de_DE.ISO8859-1/books/faq</filename>:</para>

	<screen>&prompt.user; <userinput>cvs checkout doc/de_DE.ISO8859-1/books/faq</userinput></screen>
      </step>

      <step>
        <para>Jetzt k&ouml;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
          das zeitaufwendige Transformationen vorgenommen
          werden.</para>

	<screen>&prompt.user; <userinput>make lint</userinput></screen>

        <!--?
        Glossar sollte vorhanden sein. Darin dann erkl&auml;ren,
        was mit Ziel- und Quelldokument gemeint ist.
        Oliver Fischer
        -->

	<para>Soll anschlie&szlig;end das Zieldokument erstellt
          werden, kann mit Hilfe der Variable
          <varname>FORMATS</varname> bestimmt werden, welche
          Ausgabeformate erzeugt werden sollen. Unterst&uuml;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&uuml;tzten Formate befindet sich am Anfang der Datei
          <filename>doc/share/mk/doc.docbook.mk</filename>. Bei der
          Verwendung dieser Variable ist es wichtig, darauf zu achten,
          da&szlig; die Angabe der gew&uuml;nschten Formate in
          Anf&uuml;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&szlig; m&uuml;ssen die &Auml;nderungen an das
          FDP mittels &man.send-pr.1; eingesandt werden.</para>
      </step>
    </procedure>
  </sect1>
</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->

