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.