doc/de_DE.ISO8859-1/books/fdp-primer/overview/chapter.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- 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: r46642

-->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview">
  <title>Überblick</title>

  <para>Herzlich Willkommen beim FreeBSD-Dokumentationsprojekt
    (auch nur <acronym>FDP</acronym> genannt). Qualitativ hochwertige
    Dokumentation ist sehr wichtig für den Erfolg von &os;.  Jeder
    Beitrag, der zu diesem Projekt geleistet wird, ist ungemein wertvoll.</para>

  <para>Dieses Dokument macht den Leser mit dem
    <acronym>FDP</acronym> vertraut und erklärt, wie man
    selbst Dokumente erstellt und einreicht und wie die verfügbaren
    Werkzeuge effektiv beim Schreiben eingesetzt werden
    können.</para>

  <para>Jeder kann zum <acronym>FDP</acronym> beitragen.  Die einzige
    Voraussetzung ist die Bereitschaft, helfen zu wollen.</para>

  <para>Nach dem Lesen dieses Dokuments werden Sie in der Lage sein,</para>

  <itemizedlist>
    <listitem>
      <para>die vom <acronym>FDP</acronym> betreuten Dokumente zu
	erkennen,</para>
    </listitem>

    <listitem>
      <para>die benötigten Dokumentations-Werkzeuge und Dateien
	zu installieren,</para>
    </listitem>

    <listitem>
      <para>Änderungen an der Dokumentation vorzunehmen,</para>
    </listitem>

    <listitem>
      <para>Änderungen zur Begutachtung durch das FDP
        einreichen können.</para>
    </listitem>
  </itemizedlist>

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

    <para>Das FDP umfasst vier verschiedene Kategorien:</para>

    <itemizedlist>
        <listitem>
          <para><emphasis>Handbook:</emphasis>  Das Handbuch ist die
	    umfassende Quelle und Referenz für &os;-Benutzer.</para>
        </listitem>

        <listitem>
	  <para><emphasis>FAQ:</emphasis>  Eine Sammlung von kurzen
	    Fragen und Antworten zu Themen, die auf den
            verschiedenen Mailinglisten und in auf &os; spezialisierten
	    Foren regelmäßig diskutiert werden.  Lange und komplizierte
	    Antworten werden Sie hier nicht finden.</para>
        </listitem>

        <listitem>
	  <para><emphasis>Manualpages:</emphasis>  Die englischen
	    Manualpages werden normalerweise 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>
        </listitem>

         <listitem>
	  <para><emphasis>Die Webseite:</emphasis>  Die Hauptpräsenz
	    von &os; im Internet, zu erreichen unter <link
	    xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org</link>
            oder einem der zahlreichen Spiegelserver.  Für viele Menschen
            ist sie der erste Kontakt mit &os;.</para>
	</listitem>
    </itemizedlist>

    <para>Übersetzer-Teams sind für die Übersetzung des Handbuchs und
      der Webseite in verschiedene Sprachen verantwortlich.  Manualpages
      werden derzeit nicht übersetzt.</para>

    <para>Die Quellen für die FreeBSD-Website, das &os; Handbuch
      sowie die &os; <acronym>FAQ</acronym> werden im
      Dokumentations-Repository von &os; verwaltet, das Sie über
      <literal>https://svn.FreeBSD.org/doc/</literal> erreichen
      können.</para>

    <para>Manualpages werden von &os; im einem eigenen
      Quellcode-Repository verwaltet, das Sie über
      <literal>https://svn.FreeBSD.org/base/</literal> erreichen
      können.</para>

   <para>Committ-Nachrichten des <acronym>FDP</acronym>
      sind über <application>svn</application> abrufbar und werden
      zusätzlich unter
      <uri xlink:href="&a.svn-doc-all.url;">&a.svn-doc-all.url;</uri>
      archiviert.</para>

    <para>Beide Repositories sind auch über ein Web-Interface erreichbar:
      <link xlink:href="https://svnweb.FreeBSD.org/doc/"></link> sowie
      <link xlink:href="https://svnweb.FreeBSD.org/base/"></link>.</para>

    <para>Viele Menschen haben &os;-spezifische 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 <acronym>FDP</acronym> bemüht sich,
      so viele Verweise wie möglich auf solche Quellen
      bereitzustellen.</para>
  </sect1>

  <sect1 xml:id="overview-quick-start">
    <title>Schnellstart</title>

    <para>Dieser Abschnitt beschreibt, was Sie tun müssen, bevor
      Sie Änderungen an der &os;-Dokumentation vornehmen können.
      Abonnieren Sie zuerst die Mailingliste &a.doc;.  Einige Mitglieder
      dieser Mailingliste sind auch auf dem <acronym>IRC</acronym>-Kanal
      <literal>#bsddocs</literal> auf <link
      xlink:href="http://www.efnet.org/">EFnet</link> erreichbar.  Nehmen
      Sie mit Ihnen Kontakt auf, wenn Sie Fragen oder Probleme bei
      der Arbeit an der &os;-Dokumentation haben.</para>

    <procedure>
      <step>
	<para>Installieren Sie den Metaport
	  <package>textproc/docproj</package> als Port oder Paket, um
	  automatisch alle für die Arbeit an der Dokumentation benötigten
	  Werkzeuge zu installieren.</para>
      </step>

      <step>
	<para>Installieren Sie eine lokale Arbeitskopie der Dokumentation
	  von einem Spiegelserver des &os;-Repository nach
	  <filename>~/doc</filename> (lesen Sie dazu
	  auch <xref linkend="working-copy"/>).</para>

	<screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>~/doc</replaceable></userinput></screen>
      </step>

      <step>
	<para>Ihr Texteditor sollte für die Arbeit an der
	  &os;-Dokumentation wie folgt konfiguriert sein:</para>

	  <itemizedlist>
	    <listitem>
	      <para>Zeilenumbruch nach 70 Zeichen.</para>
	    </listitem>
	    <listitem>
	      <para>Tabstop auf 2 Zeichen.</para>
	    </listitem>
	    <listitem>
	      <para>8 Leerzeichen sollen durch einen Tabstop ersetzt
		werden.</para>
	    </listitem>
	  </itemizedlist>

	  <para>Konfigurationen für einige häufig verwendete Editoren
	    finden Sie im <xref linkend="writing-style"/>.</para>
      </step>

      <step>
	<para>Aktualisieren Sie Ihre lokale Arbeitskopie:</para>

	<screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen>
      </step>

      <step>
	<para>Bearbeiten Sie die Datei.  Bevor Sie umfangreiche Änderungen
	  an einer Datei vornehmen, kündigen Sie die geplanten Änderungen
	  bitte auf der Mailingliste an.</para>

	<para>Eine Auflistung häufig verwendeter Tags und
	  Entities finden Sie in <xref linkend="xhtml-markup"/> und
	  in <xref linkend="docbook-markup"/>.</para>
      </step>

      <step>
	<para>Nachdem Sie Ihre Änderungen vorgenommen haben, prüfen
	  Sie diese auf potentielle Probleme:</para>

	<screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen>

	<para>Werden Fehler gemeldet, editieren Sie die Datei erneut.
	  Speichern Sie das Ergebnis und fühen Sie den Test erneut aus.
	  Wiederholen Sie dies solange, bis keine Fehler mehr gemeldet
	  werden.</para>
      </step>

      <step>
	<para>Bauen Sie die Dokumentation <emphasis>immer</emphasis>,
	  bevor Sie Änderungen einreichen.  Dazu führen Sie
	  <userinput>make</userinput> im Hauptverzeichnis des
	  Dokuments aus, dass Sie gerade bearbeiten.  Um beispielsweise
	  die deutsche Version des &os;-Handbuchs als einzelne
	  <acronym>HTML</acronym>-Dateien zu bauen, führen Sie
	  <userinput>make</userinput> im Verzeichnis
	  <filename>de_DE.ISO8859-1/books/handbook/</filename> aus.
	  Durch diesen Schritt wird sichergestellt, dass Ihre
	  Änderungen den Bau der Dokumentation nicht wegen eines
	  Fehlers abbrechen.</para>
      </step>

      <step>
	<para>Wenn Ihre Änderungen abgeschlossen und erfolgreich
	  getestet wurden, erzeugen Sie eine
	  <quote>Differenzdatei</quote> mit Ihren Änderungen:</para>

	<screen>&prompt.user; <userinput>cd ~/doc</userinput>
&prompt.user; <userinput>svn diff &gt; <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen>

	<para>Geben Sie der Differenzdatei einen aussagekräftigen Namen.
	  Im angegebenen Bespiel wurden Änderungen im Abschnitt
	  <filename>bsdinstall</filename> des Handbuchs vorgenommen.</para>
      </step>

      <step>
	<para>Reichen Sie Ihre Änderungen über das webbasierte <link
	  xlink:href="&url.base;/support.html#gnats">Problembericht-Formular</link>
	  ein.  Geben Sie eine kurze Beschreibung in der Form
	  <emphasis>[patch] <replaceable>kurze Beschreibung des Problems</replaceable></emphasis>
	  ein.  Als Kategorie wählen Sie <literal>docs</literal>
	  und als Klasse <literal>doc-bug</literal>.  Danach geben
	  Sie eine Beschreibung Ihrer Änderungen ein sowie eventuelle
	  weitere wichtige Punkte.  Verwenden Sie danach den Button
	  <guibutton>[&nbsp;Browse...&nbsp;]</guibutton>, um Ihre
	  Differenzdatei hochzuladen.</para>
	</step>
    </procedure>
  </sect1>
</chapter>