********************************************
Kurzbeschreibung zur SuSE Klasse susedoc.cls
********************************************

(c) 2001 SuSE Linux AG, Nrnberg, Thomas Schraitle
<documentation@suse.de>

Dieses README soll einen kurzen Einblick in die Implementierung
der SuSE Klasse geben. Ich kann leider nicht vollstndig
auf die Details eingehen; falls weitere Informationen bentigt
werden, empfehle ich die Linkliste am Ende dieses Dokuments.


Inhalt:

1. Installation
2. Inhalt
   a. Allgemeines
   b. DTX-Dateien
   c. INS-Dateien
   d. STY-Dateien

3. Aufruf
   a. STY-Dateien generieren
   b. Dokumentation erzeugen
   c. bersicht ber den Prozess

4. Implementierung
5. CVS-Tags
6. Literatur & Links

--------------------------------------------------------------


1. Installation
-----------------------------------------------------------------

a. Mglichkeiten
Es gibt zwei Mglichkeiten, die Klasse susedoc zu installieren:

1. ber ein vorgefertigtes RPM-Paket
2. ber CVS


Vorgefertigte RPM-Pakete befinden sich unter 
http://w3.suse.de/~lxbuch/susedoc und knnen wie blich mit dem
Befehl rpm eingespielt werden.

Fr die CVS-Version mssen nachfolgend die folgenden Schritte ausgefhrt werden.


b. Vorbedingungen
Es werden folgende Programmversionen bentigt:

* autoconf Version 2.52 (oder hher)
* LaTeX    Von 2000/06/01 oder spter


c. Erstellung des Makefiles
Nach dem Auschecken bzw. Entpacken wird in der Shell folgendes
eingegeben:

> make -f Makefile.cvs

Dies produziert folgende Meldungen an deren Ende das Makefile
erstellt wird.

-----
 aclocal
 automake --add-missing --copy --force-missing
 autoconf
 ./configure --prefix=/usr
 checking for a BSD compatible install... /usr/bin/install -c
 checking whether build environment is sane... yes
 checking for mawk... no
 checking for gawk... gawk
 checking whether make sets ${MAKE}... yes
 configure: creating ./config.status
 config.status: creating Makefile
-----

Jetzt kann mittels "make help" eine Liste der "Ziele" angegeben werden.
Ein "Ziel" wird mit dem Aufruf "make <ZIEL>" aktiviert, z.B. wird
durch "make userdoc" die Benutzerdokumentation erstellt.

Um die susedoc Klasse _lokal_ zu installieren, gibt man folgendes
ein:

> make sty instlocal

Dies erzeugt eine Flut von Meldungen (mit vielen %-Zeichen).
Am Ende wird (falls noch nicht vorhanden) im Homeverzeichnis
das Verzeichnis ".TeX" erstellt. Dorthin werden alle klassenrelevanten
Dateien hineinkopiert.

Die susedoc-Klasse ist jetzt einsatzbereit.

Evlt. mu noch die TEXINPUT-Variable entsprechend gesetzt werden,
falls dies nicht durch das Makefile bereits erledigt wird.



2. Inhalt
-----------------------------------------------------------------

a. Allgemeines
Der Inhalt dieses Archivs besitzt folgende Dateien:

Makefile               - Makefile zum einfachen Erstellen. Einfach
                         "make help" aufrufen zeigt einen Hilfetext an.
Makefile.cvs, Makefile.am, configure.ac
                       - Wird zum Erstellen des Makefiles verwendet
main.ins               - Hauptinstallationsdatei
package.ins            - Installationsdatei zum Erstellen der Stildateien
postscript-fonts.tex   - Testdatei fr PostScipt-Fonts
susedoc.dtx            - Hauptdatei fr die Klasse
susedoc-<LANG>.dtx     - Sprachabhngige Definitionen
susedoc-txtlayout.dtx  - Enthlt SuSE-spezifische Makros, Boxen, Listen
                         u.a. Definitionen
susedoc-titlepage.dtx  - Makro-Definitionen zur Titelseite
susedoc-empty.dtx      - Leere DTX-Datei, als Beispiel fr weitere Module
susedoc-ind-gloss.dtx  - Glossar und Indizes
susedoc-gglo.ist       - Stildatei fr Glossar
susedoc-gind.ist       - Stildatei fr Index
source.ist             - Stildatei fr makeindex


b. DTX-Dateien

DTX-Dateien sind "dokumentierte LaTeX" Dateien, d.h. sie beinhalten
normalen LaTeX-Code _und_ Codefragmente. Der gesamte LaTeX-Kern
ist in dieser Art geschrieben. Das leistungsfhige "docstrip"
Paket kann diese Kommentare entfernen und die eigentliche Stildatei
generieren.

Damit Quellcode von Dokumentation unterschieden werden kann, wird
folgendes Schema angewandt: Die Dokumentation ist in Zeilen
untergebracht, die mit dem %-Zeichen beginnen. Codefragmente werde
durch \begin{macrocode} ... \end{macrocode} eingeschachtelt, z.B.:

---- Beispiel 1: Auszug aus einer DTX-Datei
% \section{Einfhrung}
% Diese Zeile beinhaltet einen Abschnitt mit dem Titel "Einfhrung".
%
%    \begin{macrocode}
\newcommand{\hallo}[#1]{Hallo #1}
%    \end{macrocode}
----

Wie man sieht, wird ein neues Makro "\hallo" definiert. In der
technischen Dokumentation steht vor diesem Feld eine Zeilennummer.


c. INS-Dateien

INS-Dateien (von INStruction) sind gewissermaen "Batchdateien",
die aus einer oder mehreren DTX-Datei(en) z.B. eine Stildatei (.sty)
erzeugen. Hierzu wird das Paket docstrip verwendet.

---- Beispiel 2: Auszug aus einer INS-Datei
\generate{%
 \file{test.sty}{\from{test.dtx}{package}}
}
----

In Beispiel 2 sehen wir einen Teil einer INS-Datei. Es wird der
Befehl \generate aufgerufen; damit dieser den Umwandlungsprozess
steuern kann, muss diesem noch einige Parameter mitgegeben werden.
Dies wird mit dem Befehl \file getan.

Der \file-Befehl erzeugt eine Stildatei (hier: test.sty). Diese
bekommt er aus der dokumentierten Datei test.dtx. Der Text "package"
ist eine Markierung innerhalb der DTX-Datei, die fr diesen Umwandlungsprozess
verwendet werden soll. In der Regel lautet diese Markierung "package"
fr Pakete bzw. "class" fr Klassen. Allerdings bleibt es dem Autor
freigestellt einen andere n Text zu verwenden. In unseren DTX-Dateien
wurden bis auf wenige Ausnahmen (Index, Glossar und Sprachdateien) nur
"package" und "class" verwendet.

Es knnen hier auch mehrere solchen Marken angegeben werden
(ist natrlich von der DTX-Datei abhngig). Weitere Informationen
lassen sich aus der Datei "package.ins" erhalten.



d. STY-Dateien

Die STY-Dateien werden _nicht_ verndert, da sie aus der DTX-Datei
generiert werden.


3. Aufruf
-----------------------------------------------------------------


a. STY-Dateien generieren

Um aus DTX-Dateien die STY-Dateien zu erzeugen, gibt es die INS-Datei
"package.ins". Aufgerufen wird dies folgendermaen:

  latex package.ins

Es erscheinen einige Meldungen, und am Ende wird eine kurze Statistik
ausgegeben. Am Ende sind die entsprechenden STY-Dateien erzeugt worden.


b. Technische Dokumentation erzeugen

Fr die gesamte Dokumentation gibt es die LaTeX-Datei "susedoc-src.tex". Diese
muss mit LaTeX bearbeitet werden, um alle vorhandenen DTX-Dateien
einzubinden. Anschlieend ruft man makeindex auf (Generierung der Indexeintrge)
und zum Abschlu LaTeX. Das ganze sieht dann ungefhr so aus:

  latex susedoc-src.tex
  latex susedoc-src.tex
  makeindex -s source.ist susedoc-src.idx
  latex susedoc-src.tex

Diese Aufrufe erledigt auch das vorhandene Makefile indem man einfach "make doc"
eingibt.



c. bersicht ber den Prozess

Um das ganze nochmals zusammenzufassen, hier eine Grafik:

                       +-----+
latex package.ins  --->| DTX | ---> *.sty
                       +-----+


4. Implementierung
-----------------------------------------------------------------

Die Hauptklasse ist die Datei "susedoc.cls". Innerhalb dieser werden
die anderen Module nachgeladen. Folgende Module sind z.Z. definiert:

susedoc-fonts:     Zeichensatzdefinitionen
susedoc-<LANG>:    Sprachspezifische Texte
susedoc-titlepage: Fr die Erstellung der Titelseite eines SuSE-Buchs
susedoc-txtlayout: Alle textuellen Definitionen fr das Textlayout
                   (z.B. Listen, Tabellen, Abbildungen, ...)
susedoc-indgloss:  Index- und Glossarstildateien. Dieses Paket wird
                   _nicht_ geladen, da die enthaltenen Stildateien
                   von dem Programm makeindex bentigt werden.


Die Reihenfolge der einzelnen Modulaufrufe ist folgendermaen festgelegt:

susedoc.cls
\
 +- susedoc-fonts.sty
 |
 +- susedoc-<LANG>.sty
 |
 +- susedoc-titlepage.sty
 |
 +- susedoc-txtlayout.sty


5. CVS-Tags
-----------------------------------------------------------------

Es gibt Versuche, die susedoc-Klasse mehr portabel zu DocBook zu gestalten.
Daher gibt es im CVS den Tag "SUSEDOC_3_TEST".
Die Versionsnummer von susedoc wird auf 3 erhht, wenn alles stabil
genug ist.


6. Literatur & Links
-----------------------------------------------------------------

* ftp://ftp.dante.de/tex-archive/macros/latex/base/doc.dtx
  Doc - Modul; dient zur Formatierung der DTX-Dateien.
* ftp://ftp.dante.de/tex-archive/macros/latex/base/docstrip.dtx
  DocStrip: Wird bentigt, um aus DTX-Dateien andere Dateien zu generieren.
