A FreeBSD Dokumentációs Projekt: SGML

A dokumentációs munkákhoz a Dokumentációs Projekt az SGML nyelvet használja mint alapvetõ eszközt.

Az SGML jelentése: Standard Generalized Markup Language.

Dióhéjban (és elnézést kérünk mindenki SGML szakértõtõl, akit sért a következõ kijelentés) úgy foglalhatnánk össze, hogy az SGML egy olyan nyelv, amellyel további nyelveket hozhatunk létre.

Talán már mi magunk is használtuk az SGML-t anélkül, hogy tudtunk volna róla. A honlapok készítésére használt HTML nyelv például olyan formális leírással rendelkezik, amely az SGML nyelven íródott. Természetesen ez nem azt jelenti, hogy amikor HTML nyelven írunk valamit, akkor az SGML nyelvet használjuk (és fordítva sem). Ez csupán egy olyan nyelv, amelynek szabályait az SGML segítségével fektették le.

Sok leíró nyelv létezik, melynek alapjait SGML nyelven írták. A HTML az egyik ezek közül. Egy másik példa erre a “DocBook”. Ez egy olyan nyelv, melyet kifejezetten mûszaki leírások írásához terveztek, és mint ilyen, a megfelelõ formázáshoz nagyon sok ilyen típusú (tehát <a tag tartalma> alakú) taggel rendelkezik. A FreeBSD Dokumentációs Projekt ezt használja, és a nagyon pontosság érdekében még kiegészítette néhány új elemmel is.

A következõ példa bemutatja hogyan írhatunk meg egy bekezdést a HTML nyelv segítségével (a tartalom most nem fontos, csak a tagek):

    <p>A rendszer a jelszavak tárolására az
      <tt>/etc/passwd</tt> állományt használja.
      Ennek módosításához a
      <b><tt>vipw</tt></b> használata ajánlott.
      Amennyiben csak egy új felhasználót akarunk
      felvenni a rendszerbe, használjuk az
      <b><tt>adduser</tt></b> parancsot.</p>

Ugyanez a bekezdés a DocBook leírónyelvet használva így néz ki:

    <para>A rendszer a jelszavak tárolására az
      <filename>/etc/passwd</filename> állományt
      használja.  Ennek módosításához
      a <command>vipw</command> használata ajánlott.
      Amennyiben csak egy új felhasználót akarunk
      felvenni a rendszerbe, használjuk az
      <command>adduser</command> parancsot.</para>

Láthatjuk, hogy a DocBook sokkal “kifejezõbb” a HTML-nél. A HTML példában az állománynév megjelenítése “typewriter” betûtípussal történik. A DocBook ugyanezt “állománynévként” képes kezelni függetlenül attól, hogy az állománynevek formázását itt nem tárgyaljuk.

Ennek a sokkal kifejezõbb jelölési rendszernek rengeteg elõnye van:

Nem félreérthetõ vagy ellentmondásos.

Nem töltünk el idõt feleslegesen azon gondolkodva, hogy “Hmm, vajon egy állomány megjelenítéséhez a 'tt', 'b', vagy 'em' lenne megfelelõbb?”

Ehelyett egyszerûen csak a megfelelõ taget használjuk a megfelelõ helyen.

Biztosak lehetünk benne, hogy a minden <filename> taggel megjelölt rész ugyanúgy fog kinézni, amikor DocBookból más formátumokba (HTML, PostScript® stb.) alakítjuk át.
Nem kell a dokumentum megjelenésével foglalkoznunk, így kizárólag a tartalomra tudunk koncentrálni.
Mivel a dokumentáció leírásának módja egyáltalán nem kötött, ugyanaz a dokumentáció több más formátumban is könnyedén elõállítható - egyszerû szöveg, HTML, PostScript®, RTF, PDF stb.
A dokumentáció is így sokkal “intelligensebb”, tehát bonyolultabb is feladatokra felhasználható. Például lehetséges egy olyan tárgymutató automatikus elõállítása, amely a dokumentáció összes parancsát tartalmazza.

Ez olyan, mint a Microsoft® Word stíluslapjai, csak mérhetetlenül sokoldalúbb.

Természetesen ennek a sokoldalúságnak ára an:

Mivel a használható tagek száma sokkal nagyobb, tovább tart megtanulásuk és alkalmazásuk hatékony elsajátítása is.

Egy jó módszer az SGML és a DocBook elsajátítására az, ha a dokumentációk forrásaiban megfigyeljük, más szerzõk hogyan írtak le hasonló információt.
Az átalakítás nem egyszerû.

Mi a teendõ, ha nem ismerjük a DocBook rendszert? Hozzá tudunk járulni mással is?

Természetesen igen, hiszen bármely dokumentáció jobb a nem létezõ dokumentációnál. Ne aggódjunk, ha a közlésre szánt dokumentáció nem DocBook nyelven íródott!

Az eddig megszokottakhoz hasonlóan küldjünk el a dokumentációt. A projekt egy másik tagja elõ fogja venni a javasolt dokumentációt, elvégzi a konvertálást és közzéteszi. Kis szerencsével az így elkészült szöveget is visszaküldik! Ez hasznos lehet, mert így láthatjuk a dokumentáció “elõtte és utána” változatát, és remélhetõen tanulhatunk egy keveset a folyamatról.

Ez nyilvánvalóan lelassítja a közzétételi folyamatot, mivel a beküldött dokumentációt még konvertálni kell. Így pár órába, vagy pár napba is beletelhet, mire elbírálásra kerül.

További információk az SGML és a DocBook nyelvekrõl

Elsõként olvassuk el a A FreeBSD Dokumentációs Projekt irányelvei kezdõknek címû könyvet. Ennek célja, hogy átfogó leírást nyújtson minden, a FreeBSD dokumentációja kapcsán felmerülõ kérdések megválaszolásához. Igen hosszú leírás, amely kisebb részekre szedtek szét, de lehetõségünk van megtekinteni akár egészben is.

http://www.oasis-open.org/cover/sgml-xml.html: Az SGML/XML honlapja. Számtalan hivatkozás szól az SGML nyelvrõl.
http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html: "Gentle Introduction to SGML". Ajánlott olvasmány mindenkinek, aki az SGML nyelvvel a kezdõk szemszögébõl nézve szeretne közelebbrõl megismerkedni.
http://www.oasis-open.org/docbook/: A DocBook DTD-t az OASIS tartja karban. Ezek az oldalak azoknak szólnak, akik az SGML nyelvet már elsajátították és a DocBook nyelvet is tanulmányoznák.

A FreeBSD Dokumentációs Projekt kezdõlapja