mirror of https://git.FreeBSD.org/doc.git
181 lines
7.3 KiB
XML
181 lines
7.3 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/xhtml10-freebsd.dtd" [
|
|
<!ENTITY dedate "$FreeBSDde: de-www/docproj/sgml.xml,v 1.2 2008/02/24 11:23:07 jkois Exp $">
|
|
<!ENTITY reference "basiert auf: 1.28">
|
|
<!ENTITY title "FreeBSD Documentation Project: SGML">
|
|
]>
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>&title;</title>
|
|
|
|
<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
|
|
</head>
|
|
|
|
<body class="navinclude.docs">
|
|
|
|
<p>Das Documentation Project verwendet SGML zur Erstellung der
|
|
Dokumentation.</p>
|
|
|
|
<p>SGML steht für <b>S</b>tandard <b>G</b>eneralized <b>M</b>arkup
|
|
<b>L</b>anguage.</p>
|
|
|
|
<p>Kurz gesagt (SGML-Puristen mögen dies verzeihen) handelt
|
|
es sich bei SGML um eine Sprache zum Schreiben anderer
|
|
Sprachen.</p>
|
|
|
|
<p>Wahrscheinlich haben Sie SGML bereits verwendet, ohne dass Sie
|
|
sich dessen bewusst sind. So verfügt beispielsweise HTML
|
|
(die Sprache, in der zahlreiche Internetseiten geschrieben sind)
|
|
über eine formale Beschreibung, die in SGML verfasst wurde.
|
|
Wenn Sie HTML verwenden, verwenden Sie aber trotzdem <b>kein</b>
|
|
SGML, sondern eine Sprache, die in SGML definiert wurde.</p>
|
|
|
|
<p>Es gibt zahlreiche, in SGML definierte Sprachen. HTML ist
|
|
dabei lediglich eine unter vielen Sprachen. Eine weitere
|
|
bekannte Sprache ist "DocBook". Diese Sprache wurde speziell
|
|
dafür entwickelt, technische Dokumentationen zu schreiben.
|
|
Dazu verfügt sie über zahlreiche Tags (also Markierungen
|
|
der Form <tt><Tag Inhalt></tt>), um diese
|
|
Dokumentationen für deren anschließende
|
|
Formatierung zu beschreiben.
|
|
Das FreeBSD Documentation Project hat DocBook an seine
|
|
Bedürfnisse angepasst und unter anderem einige neue
|
|
Elemente definiert, um die Sprache präziser zu machen.</p>
|
|
|
|
<p>Sehen Sie sich dazu den folgenden (in HTML geschriebenen)
|
|
Absatz an. Der Inhalt ist Nebensache, konzentrieren Sie sich
|
|
auf die verwendeten Tags:</p>
|
|
|
|
<pre><![CDATA[
|
|
<p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
|
|
this file you should use <b><tt>vipw</tt></b>. However, if you just
|
|
want to add a new user you can use <b><tt>adduser</tt></b>.</p>
|
|
]]></pre>
|
|
|
|
<p>Der gleiche (diesmal in DocBook geschriebene) Absatz sieht
|
|
folgendermaßen aus:</p>
|
|
|
|
<pre><![CDATA[
|
|
<para>The system's passwords are stored in
|
|
<filename>/etc/passwd</filename>. To edit this file you should use
|
|
<command>vipw</command>. However, if you just want to add a new user
|
|
you can use <command>adduser</command>.</para>
|
|
]]></pre>
|
|
|
|
<p>Wie Sie sehen, ist DocBook "ausdrucksstärker" als HTML.
|
|
In HTML wird der Dateiname als "in Schreibenmaschinenschrift
|
|
darzustellen" markiert. In DocBook wird der Dateiname hingegen
|
|
als "filename" markiert. Es wird allerdings nicht angegeben,
|
|
wie "filename" dargestellt werden soll.</p>
|
|
|
|
<p>Diese Vorgehensweise hat mehrere Vorteile:</p>
|
|
|
|
<ul>
|
|
<li><p>Sie ist eindeutig und konsistent.</p>
|
|
|
|
<p>Sie verlieren keine Zeit mit Überlegungen wie
|
|
"Hm, ich muss einen Dateinamen darstellen, nehme ich
|
|
dafür 'tt', 'b', oder besser doch 'em'?"</p>
|
|
|
|
<p>Stattdessen verwenden Sie einfach das der jeweiligen
|
|
Situation angepasste Tag.</p>
|
|
|
|
<p>Die Konvertierung von DocBook in andere Formate wie
|
|
HTML oder PostScript® stellt sicher, dass alle
|
|
Dateinamen innerhalb des Dokuments gleich dargestellt
|
|
werden.</p>
|
|
</li>
|
|
|
|
<li><p>Sie müssen sich keine Gedanken mehr über die
|
|
Darstellung Ihres Dokuments machen, sondern können
|
|
sich auf den Inhalt konzentrieren.</p>
|
|
</li>
|
|
|
|
<li><p>Da die Dokumentation nicht an ein bestimmtes Format
|
|
gebunden ist, kann die gleiche Dokumentation in viele
|
|
verschiedene Formate (wie normalen Text, HTML, PostScript,
|
|
RTF, PDF und andere mehr) konvertiert werden.</p></li>
|
|
|
|
<li><p>Die Dokumentation ist 'intelligenter' und erlaubt dadurch
|
|
auch anspruchsvollere Dinge, wie die automatische
|
|
Erstellung eines Index mit allen innerhalb des Dokuments
|
|
verwendeten Befehlen.</p></li>
|
|
</ul>
|
|
|
|
<p>Mit DocBook erstellte Dokumente haben eine gewisse
|
|
Ähnlichkeit mit den von Microsoft® Word bekannten
|
|
Dokumentvorlagen, sind aber sehr viel mächtiger.</p>
|
|
|
|
<p>Diese besonderen Fähigkeiten haben aber ihren Preis:</p>
|
|
|
|
<ul>
|
|
<li><p>Da es sehr viele Tags gibt, dauert es länger, bis
|
|
Sie alle kennen werden und optimal einsetzen können.</p>
|
|
|
|
<p>Um die Lernkurve zu verflachen, ist es sehr hilfreich,
|
|
sich Dokumentationen anderer Autoren anzusehen, um zu sehen,
|
|
wie diese ähnliche Informationen beschreiben.</p>
|
|
</li>
|
|
|
|
<li><p>Der Konvertierungsprozess ist relativ komplex.</p></li>
|
|
</ul>
|
|
|
|
<h2>Sie können kein DocBook. Können Sie das Documentation
|
|
Project trotzdem unterstützen?</h2>
|
|
|
|
<p>Natürlich. Jede Dokumentation ist besser als keine
|
|
Dokumentation. Es ist kein großes Problem, wenn Ihr Beitrag
|
|
nicht als DocBook formatiert ist.</p>
|
|
|
|
<p><a href="submitting.html">Reichen</a> Sie Ihren Beitrag einfach
|
|
ein. Jemand aus dem Documentation Project wird Ihren Beitrag
|
|
übernehmen, ihn in DocBook formatieren und committen.
|
|
Vielleicht erhalten Sie den formatierten Text sogar zurück.
|
|
Dann können Sie einen "Vorher-/Nachher-Vergleich"
|
|
durchführen und so etwas mehr über DocBook lernen.</p>
|
|
|
|
<p>Da Ihr Beitrag in diesem Fall aber zuerst in DocBook formatiert
|
|
werden muss, verlangsamt sich der Konvertierungsprozess etwas,
|
|
es kann daher bis zu einigen Tagen dauern, bis Ihr Beitrag
|
|
committet wird.</p>
|
|
|
|
<h2>Gibt es weitere Informationen zu SGML und DocBook?</h2>
|
|
|
|
<p>Lesen Sie zuerst den <a
|
|
href="&enbase;/doc/de_DE.ISO8859-1/books/fdp-primer/index.html">
|
|
<b>Documentation Project Primer</b></a>. Dieser enthält eine
|
|
ausführliche Beschreibung aller Dinge, die Sie zur Arbeit
|
|
an der FreeBSD Dokumentation benötigen. Er ist in mehrere
|
|
Abschnitte unterteilt, kann aber auch als <a
|
|
href="&enbase;/doc/de_DE.ISO8859-1/books/fdp-primer/book.html">
|
|
<b>eine einzelne große Seite</b></a> aufgerufen werden.</p>
|
|
|
|
<dl>
|
|
<dt><a
|
|
href="http://www.oasis-open.org/cover/sgml-xml.html"><b>http://www.oasis-open.org/cover/sgml-xml.html</b></a></dt>
|
|
|
|
<dd><p>Die offiziellen SGML/XML-Internetseiten mit zahlreichen
|
|
Links zu SGML-Ressourcen.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html"><b>http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html</b></a></dt>
|
|
|
|
<dd><p>"The Gentle Introduction to SGML" ist für alle
|
|
empfehlenswert, die mehr über SGML (insbesondere aus der
|
|
Sicht eines Einsteigers) wissen wollen.</p></dd>
|
|
|
|
<dt><a
|
|
href="http://www.oasis-open.org/docbook/"><b>http://www.oasis-open.org/docbook/</b></a></dt>
|
|
|
|
<dd><p>Die offizielle DocBook DTD wird von OASIS gewartet. Diese Seiten
|
|
richten sich besonders an Personen, die mit SGML bereits vertraut sind
|
|
und nun DocBook lernen wollen.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p></p><a href="docproj.html">Startseite des FreeBSD Documentation Projects</a>
|
|
</body>
|
|
</html>
|