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