Skip site navigation (1) Skip section navigation (2)

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(R) 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(R), 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(R) 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