path: root/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.sgml

<?xml version="1.0" encoding="ISO8859-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>&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>

  <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&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>Manualpages</term>

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

          <para>F&uuml;r die &Uuml;bersetzung der Manualpages 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="&url.base;/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>Die Quellen f&uuml;r die FreeBSD-Website, das &os; Handbuch
      sowie die &os; FAQ werden im <literal>doc/</literal>
      Subversion-Repository von &os; verwaltet, das Sie &uuml;ber
      <literal>svn://svn.FreeBSD.org/doc/</literal> erreichen
      k&ouml;nnen.</para>

    <para>Manualpages werden im <literal>src/</literal>
      Subversion-Repository von &os; verwaltet, das Sie &uuml;ber
      <literal>svn://svn.FreeBSD.org/base/</literal> erreichen
      k&ouml;nnen.</para>

    <para>Das bedeutet, dass alle &Auml;nderungen an den
      Dateien f&uuml;r jeden verf&uuml;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&auml;llen hat sich der Autor
      entschlossen, seine Dokumentation au&szlig;erhalb des zentralen
      FreeBSD-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 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&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>Laden Sie mit <application>svn</application> eine lokale
	  Kopie des FreeBSD-<filename>doc</filename>-Verzeichnisbaumes
	  herunter.</para>

        <para>Selbst wenn Sie nur &uuml;ber eine geringe Bandbreite
	  oder wenig freien Plattenplatz verf&uuml;gen, m&uuml;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&ouml;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&uuml;r den Fall, dass ausreichend Platz auf der
          Festplatte vorhanden ist, kann auch eine eine
          vollst&auml;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 &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>svn checkout svn://svn.FreeBSD.org/doc/head/en_US.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 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&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>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&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
          dass zeitaufw&auml;ndige 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>head/share/mk/doc.docbook.mk</filename>. Bei der
          Verwendung dieser Variable ist es wichtig, darauf zu achten,
          dass 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:
-->