Oldal navigáció átlépése (1) Fejezet navigáció átlépése (2)

Oldal Navigáció

FreeBSD Dokumentációs Projekt: SGML

A Dokumentációs Projekt az SGML nyelvet használja, mint alapvető eszközt a dokumentáció bemutatásához.

Az SGML jelentése: Standard Generalized Markup Language.

Dióhéjban, (és elnézést mindenkitől, akit sért a következő kijelentés) az SGML egy nyelv további nyelvek létrehozására.

Talán Ön is használta már az SGML-t, anélkül, hogy tudott volna róla. A HTML, amely nyelven a honlapok készülnek, rendelkezik formális leírással, amely SGML nyelven íródott. Mikor HTML nyelven ír, nem az SGML nyelvet használja (és fordítva sem), csak egy olyan nyelvet, 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 technikai leírások írásához terveztek, és mint ilyen, sok taggel rendelkezik (amelyek így néznek ki: <Tag tartalma>), a technikai leírások megfelelő formázásához. A FreeBSD Dokumentációs Projekt ezt használja, kiegészítve néhány új elemmel a még nagyobb precizitás érdekében.

A következő példa bemutatja, hogyan írhat bekezdést a HTML nyelv segítségével (a tartalomtól eltekintve, csak a tageket nézze):

      <p>A rendszer a jelszavak t&aacute;rol&aacute;s&aacute;ra a
        <tt>/etc/passwd</tt> f&aacute;jlt haszn&aacute;lja.  Ennek
        m&oacute;dos&iacute;t&aacute;s&aacute;hoz a <b><tt>vipw</tt></b>
        haszn&aacute;lata ajánlott.  Amennyiben csak egy &uacute;j
        felhaszn&aacute;l&oacute;t akar felvenni a rendszerbe,
        haszn&aacute;lhatja 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&aacute;rol&aacute;s&aacute;ra a
    <filename>/etc/passwd</filename> f&aacute;jlt haszn&aacute;lja.  Ennek
    m&oacute;dos&iacute;t&aacute;s&aacute;hoz a <command>vipw</command>
    haszn&aacute;lata aj&aacute;nlott.  Amennyiben csak egy &uacute;j
    felhaszn&aacute;l&oacute;t akar felvenni a rendszerbe,
    haszn&aacute;lhatja az <command>adduser</command> parancsot.</para>

Amint látja, a DocBook sokkal "kifejezőbb" a HTML-nél. A HTML példában a fájlnév megjelenítése "typewriter" betűtípussal történik. A DocBook ugyanezt "fájlnév"-ként képes kezelni, függetlenül attól, hogy a fájlnév leírá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 időt azon gondolkodva, hogy "Hmm, vajon egy fájlnév megjelenítéséhez 'tt', 'b', vagy 'em' lenne megfelelőbb?"

    Ehelyett a megfelelő taget használhatja a megfelelő helyen.

    A DocBookból más formátumokba (HTML, PostScript®, stb.) történő átalakítás során biztos lehet abban, hogy minden <filename> ugyanúgy fog kinézni.

  • Elfelejthet a dokumentum tálalásának módjával foglalkozni, így kizárólag a tartalomra koncentrálhat.

  • 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ó sokkal intelligensebb, tehát intelligensebb feladatokra haszná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ílusai, csak mérhetetlenül sokoldalúbb.

Természetesen a sokoldalúságnak ára van:

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

    Egy jó módszere az SGML és a DocBook elsajátításának az, ha sok példa dokumentáció forrásában megfigyeljük, más szerzők hogyan írtak le hasonló információt.

  • Az átalakítás nem egyszerű.

Mi a teendő, ha nem ismeri a DocBook rendszert? Hozzájárulhat mással is?

Természetesen igen. Bármely dokumentáció jobb a nem létező dokumentációnál. Amennyiben rendelkezik néhány közlésre szánt dokumentációval, de azok nem DocBook nyelven íródtak, ne aggódjon!

Küldje el a dokumentációt, mint normális esetben. 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 elküldik Önnek! Ez hasznos lehet, mert így megtekintheti a dokumentáció "előtte és utána" változatát, és remélhetően tanul egy keveset a leíró folyamatbó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-ről és a DocBookról

Először is olvassa 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 oldalakra van tagolva, de lehetősége van megtekinteni egy oldalként, egészben.

http://www.oasis-open.org/cover/sgml-xml.html

Az SGML/XML honlap. Számtalan hivatkozás az SGML-ről.

http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html

"Gentle Introduction to SGML". Ajánlott olvasmány mindenkinek, aki közelebbről akar megismerkedni az SGML nyelvvel, a kezdők szemszögéből nézve.

http://www.oasis-open.org/docbook/

A DocBook DTD-t az OASIS gondozza. Ezek az oldalak azoknak szólnak, akik az SGML nyelvet már elsajátították és a DocBook-ot tanulmányoznák.

FreeBSD Dokumentációs Projekt kezdőlap