A DocBook jelölőnyelvet eredetileg a HaL Computer Systems és az O'Reilly & Associates dolgozta ki a műszaki jellegű dokumentációk írásához[2], illetve 1998 óta a DocBook Műszaki Bizottság tartja karban. Mint ilyen nyelv, eltérően a LinuxDoc és a HTML megoldásaitól, a DocBook erősen olyan jelölések irányába orientálódik, amelyek nem azt írják le hogyan, hanem mit jelenítsünk meg.
Formális
kontra
informális
: Bizonyos elemeknek létezik ún. formális és informális változata. A formális változat általában egy címből és az adott elem informális változatából áll. Az informális változat nem tartalmaz címet.
A DocBook használatához szükséges DTD a Portgyűjteményből a textproc/docbook porton keresztül érhető el. Ez a textproc/docproj port részeként automatikusan telepítődik.
A FreeBSD Dokumentációs Projekt kiterjesztette a hivatalos DocBook DTD-t további elemekkel. Segítségükkel bizonyos jelölések sokkal pontosabbá tehetőek.
A kizárólag a FreeBSD esetén alkalmazott elemeket egyértelműen jelezni fogjuk a felsorolásban.
A dokumentum további részében a „DocBook” kifejezés a DocBook DTD FreeBSD kiterjesztéseivel együtt értendő.
Szeretnénk megemlíteni, hogy a
hozzáadott kiegészítésekben azonban
semmi olyan nincs, ami kizárólag a FreeBSD-re
vonatkozna, egyszerűen csak a Projektben felmerült
igények mentén szeretne alkalmazni
néhány javítást. Ha más
UNIX® jellegű rendszerek (NetBSD, OpenBSD, Linux, stb.)
fejlesztőit esetleg érdekelné a DocBook
további fejlesztése, kérjük,
vegyék fel velünk a kapcsolatot a Documentation Engineering Team <doceng@FreeBSD.org>
címén.
A FreeBSD kapcsán alkalmazott kiterjesztések (jelenleg) nem érhetőek el a Portgyűjteményből, hanem a FreeBSD repositoryban találjuk meg a doc/share/xml/freebsd.dtd helyen.
A DocBook a testreszabott változatok formális publikus azonosítóira vonatkozó irányelvei szerint a FreeBSD kiterjesztéseivel bővített DocBook DTD formális publikus azonosítója a következő lesz:
PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"
A DocBook többféle módon kínál lehetőségeket a dokumentumok szerkezetének kialakítására. A FreeBSD Dokumentációs Projektben a DocBook dokumentumok két alapvető fajtáját használjuk, a könyvet és a cikket.
A könyvek fejezetekből
(chapter
) állnak, amelyek
használata kötelező. A könyv és a
fejezetek közé még további
szervezési rétegként beilleszhetőek
részek (part
) is.
Például a FreeBSD kézikönyv
szerkezetét is ennek megfelelően alakítottuk
ki.
A fejezetek tartalmazhatnak (vagy sem) egy vagy több
szakaszt, amelyeket sect1
elemekkel
jelezhetünk. Amennyiben egy szakasz újabb szakaszt
tartalmaz, akkor használjuk a sect2
elemet, és így tovább egészen a
sect5
szintig.
A fejezetek és a szakaszok tartalmazzák a dokumentum tartalmának fennmaradó részét.
Egy cikk egy könyvnél egyszerűbb
felépítésű, és nem tartalmaz
fejezeteket. Helyette a cikkek tartalmát egy vagy
több szakaszba szervezzük, a könyvnél
már említett sect1
(sect2
és így tovább)
elemek segítségével.
A készítendő dokumentációról értelemszerűen jellegének mérlegelésével tudjuk eldönteni, hogy könyvként esetleg cikk-ként érdemesebb jelölni. A cikk formátum választása leginkább olyan információk esetén célszerű, ahol nincs szükségünk külön fejezetekre. Röviden szólva tehát egy viszonylag rövid, legfeljebb 20-25 oldalas írást takar. A könyv formátum ezzel szemben leginkább olyan esetekben alkalmazható, amikor az információ fejezetekre bontható, amelyhez függelékek és hasonlók is társulhatnak.
A FreeBSD-hez készített cikkek mindegyikét cikk-ként jelöltük, miközben például ez a dokumentum, a FreeBSD GYIK, és a FreeBSD kézikönyv könyvként került jelölésre.
A könyvek tartalmát egy
book
elemben adjuk meg. Ez a
jelölő amellett, hogy magában foglalja a
könyv teljes felépítését,
tovább információkat tud tárolni
magáról a könyvről. Ez lehet
akár hivatkozási célokat
szolgáló metainformáció, vagy
éppen a címlap
elkészítéséhez
szükséges egyéb
leírás.
A könyvre vonatkozó további
információkat egy bookinfo
elemen belül adhatjuk meg.
book
és
bookinfo
elemek
segítségével definiált
könyvsablon<book> <bookinfo> <title>Ide írjuk a címet
</title> <author> <surname>Vezetéknév
</surname> <firstname>Keresztnév
</firstname> <affiliation> <address><email>E-mail cím
</email></address> </affiliation> </author> <copyright> <year>2008
</year> <holder role="mailto:E-mail cím
">Név
</holder> </copyright> <releaseinfo>$FreeBSD$</releaseinfo> <abstract> <para>Ide kerüljön a könyv tartalmának rövid összefoglalása.
</para> </abstract> </bookinfo> … </book>
A cikk tartalma az article
elembe
kerül. A dokumentum szervezésén
kívül ennek az elemnek feladata
lehetőséget kínálni további
információk elhelyezésére. Ez
lehet hivatkozási célokra alkalmas
metainformáció, vagy például a
címlap előállításához
szükséges egyéb adatok.
A cikk-kel kapcsolatos további
információk egy articleinfo
elemben adhatóak meg.
article
és
articleinfo
elemek
segítségével definiált
cikksablon<article> <articleinfo> <title>Ide írjuk a címet
</title> <author> <surname>Vezetéknév
</surname> <firstname>Keresztnév
</firstname> <affiliation> <address><email>E-mail cím
</email></address> </affiliation> </author> <copyright> <year>2008
</year> <holder role="mailto:E-mail cím
">Név
</holder> </copyright> <releaseinfo>$FreeBSD$</releaseinfo> <abstract> <para>Ide kerüljön a cikk tartalmának rövid összefoglalása.
</para> </abstract> </articleinfo> … </article>
A chapter
elem
használatával tudunk fejezeteket jelölni.
Minden fejezetnek kötelezően rendelkeznie kell egy
címmel, vagyis egy title
elemmel. A
cikkek nem tartalmazhatnak fejezeteket,
kizárólag könyvek számára
tartják fenn.
A fejezetek nem lehetnek üresek, a
title
elem mellett még tartalmazniuk
kell valamilyen másik elemet is. Az üres
fejezetek készítéséhez
használjunk egy üres bekezdést.
A könyvekben a fejezetek további szakaszokra,
alszakaszokra stb. bonthatóak (de nem
kötelező). A cikkekben azonban a szakaszok az
alapvető szervezőelemek, ezért minden cikknek
legalább egy szakaszt tartalmaznia kell. A szakaszok
létrehozására a
sect
elemet
használhatjuk, ahol az n
n
szám adja meg a szakasz szintjét.
Az első ilyen
sect
elem a
n
sect1
, amelyből egy fejezetben egy
vagy több is szerepelhet. Ezek egy vagy több
sect2
elemet tartalmazhatnak, és
így tovább egészen az
sect5
szintjéig.
<chapter> <title>Minta fejezet</title> <para>Egy kis fejezetbeli szöveg.</para> <sect1> <title>Első szakasz (1.1)</title> … </sect1> <sect1> <title>Második szakasz (1.2)</title> <sect2> <title>Első alszakasz (1.2.1)</title> <sect3> <title>Első al-alszakasz (1.2.1.1)</title> … </sect3> </sect2> <sect2> <title>Második alszakasz (1.2.2)</title> … </sect2> </sect1> </chapter>
Láthatjuk, hogy ebben a példában a szakaszok neveiben megjelenik a szakaszok számozása. Ezt azonban ne írjuk bele a dokumentumainkba! A szakaszok számozását a stíluslapok végzik (erről még később szó lesz), ezekkel egyáltalán nem kell foglalkoznunk.
A book
és
chapter
elemek részéről
felkínált szervezési szintek
közé a part
elemek
alkalmazásával egy újabbat tudunk
illeszteni. Erre a cikkek esetében nincs
lehetőségünk.
<part> <title>Bevezetés</title> <chapter> <title>Áttekintés</title> ... </chapter> <chapter> <title>Mi a FreeBSD?</title> ... </chapter> <chapter> <title>Történet</title> ... </chapter> </part>
A DocBookban a bekezdések háromféle
típusát találhatjuk meg:
formalpara
, para
és simpara
.
Az iméntiek közül a legtöbb esetben
az para
elemre lesz
szükségünk. A formalpara
tartalmaz még egy title
elemet,
illetve a simpara
nem engedélyezi
bizonyos elemek használatát a
bekezdésben. Érdemes tehát inkább
következetesen a para
használatánál maradni.
para
elemA használat módja:
<para>Ez egy bekezdés. Tetszőleges egyéb elem megjelenhet benne.</para>
Így jelenik meg:
Ez egy bekezdés. Tetszőleges egyéb elem megjelenhet benne.
Az idézetblokkok egy másik dokumentumból származó, kiterjedtebb hosszúságú idézetet jelölnek, amelyeknek az aktuális bekezdéstől függetlenül kell megjelenniük. Erre valószínűleg csak nagyon ritkán lesz ténylegesen szükségünk.
Az idézetblokkok opcionálisan címeket és szerzőt is tartalmazhatnak (de akár szerepelhetnek cím vagy szerző nélkül).
blockquote
elemA használat módja:
<para>Részlet Szerb Antal <quote>A Pendragon legenda</quote> című művéből:</para> <blockquote> <title>A Pendragon legenda</title> <attribution>Szerb Antal</attribution> <para>Minden nőben azt élveztem, hogy a szimbóluma volt valaminek. Volt nő, akit azért szerettem, mert ő volt Svédország, volt nő, akit azért, mert a XVIII. századra emlékeztetett törékeny Sèvres-mivolta. Volt, akiben Jeanne d'Arc-ot álmodtam, volt, akiben az ezermellű ephesusi Dianát. Cynthiát, ha megcsókoltam, úgy éreztem, most az angol szonetekkel flörtölök, ötödfeles jambusokban. Volt, akinek édes tehénszerűségében svájci, alpesi réteket élveztem.</para> </blockquote>
Így jelenik meg:
Részlet Szerb Antal „A Pendragon legenda” című művéből:
A Pendragon legenda Minden nőben azt élveztem, hogy a szimbóluma volt valaminek. Volt nő, akit azért szerettem, mert ő volt Svédország, volt nő, akit azért, mert a XVIII. századra emlékeztetett törékeny Sèvres-mivolta. Volt, akiben Jeanne d'Arc-ot álmodtam, volt, akiben az ezermellű ephesusi Dianát. Cynthiát, ha megcsókoltam, úgy éreztem, most az angol szonetekkel flörtölök, ötödfeles jambusokban. Volt, akinek édes tehénszerűségében svájci, alpesi réteket élveztem. | ||
--Szerb Antal |
Esetenként szükségünk lehet arra, hogy bizonyos többletinformációt közöljünk az olvasóval a szövegtől elkülöníthető módon. Ez többnyire olyan „metainformáció”, amelyre a felhasználónak tekintettel érdemes lennie.
Az adott információ jellegétől
függően erre a célra a tip
(tanács), note
(megjegyzés),
warning
(felhívás),
caution
(figyelmeztetés) és
important
(fontos információ)
elemek valamelyikét tudjuk használni.
Amennyiben a közölni kívánt
információ kötődik ugyan a
szöveghez, azonban az előbbiek közül egyik
kategóriába sem sorolható be, akkor
használhatjuk a sidebar
(mellékinformáció) elemet is.
Nem teljesen tisztázott, hogy az imént felsorolt elemek közül pontosan mikor melyiket kell alkalmazni. A DocBook dokumentációja ezzel kapcsolatban a következőket javasolja:
A note
elemek olyan
információkat jelölnek, amelyek az
olvasó részéről
megszivlelendőek.
Az important
elemek a
note
elemek egyik
változata.
A caution
elemmel olyan
információt jelölnek, amelyek
ismeretének hiányában
adatvesztés vagy szoftveres károdás
következhet be.
A warning
elemek olyan
információkat jelölnek, amelyek
ismeretének hiánya hardver
károsodását,
életveszélyt vagy a végtagok
sérülését
eredményezheti.
warning
elemA használat módja:
<warning> <para>A FreeBSD telepítése után könnyen előfordulhat, hogy a Windowst teljesen le akarjuk törölni a merevlemezünkről.</para> </warning>
Így jelenik meg:
A FreeBSD telepítése után könnyen előfordulhat, hogy a Windowst teljesen le akarjuk törölni a merevlemezünkről.
Gyakran adódhatnak olyan helyzetek, amikor az olvasó felé fel kell sorolnunk valamilyen információkat, vagy egy adott cél elérése érdekében be kell mutatnunk neki egy sorszámozott, egyenként végrehajtandó lépéssorozatot.
Erre a célra rendelkezésünkre
állnak az itemizedlist
, az
orderedlist
, illetve a
procedure
elemek[3].
Az itemizedlist
és az
orderedlist
elemek hasonlóak az HTML
esetén már megismert megfelelőikhez, az
ul
és ol
elemekhez. Egy vagy több listitem
elemből állnak és mindegyik
listitem
egy vagy több blokkot
tartalmaz. A listitem
elemek a HTML
li
elemeihez hasonlóak, azonban
ebben az esetben kötelező megadni ezeket.
A procedure
elem ettől
némileg eltér. Itt step
elemekből épül fel, amelyek további
step
vagy substep
típusú elemeket foglalhatnak magukban. A
step
elemek mindegyike blokkokat
tartalmaz.
itemizedlist
,
orderedlist
és
procedure
elemekA használat módja:
<itemizedlist> <listitem> <para>Ez a felsorolás első eleme.</para> </listitem> <listitem> <para>A a felsorolás második eleme.</para> </listitem> </itemizedlist> <orderedlist> <listitem> <para>Ez az első sorszámozott elem.</para> </listitem> <listitem> <para>Ez a második sorszámozott elem.</para> </listitem> </orderedlist> <procedure> <step> <para>Csináljuk ezt.</para> </step> <step> <para>Majd csináljuk azt.</para> </step> <step> <para>Most pedig csináljuk így.</para> </step> </procedure>
Így jelenik meg:
Ez a felsorolás első eleme.
Ez a felsorolás második eleme.
Ez az első sorszámozott elem.
Ez a második sorszámozott elem.
Csináljuk ezt.
Majd csináljuk azt.
Most pedig csináljuk így.
Ha állományrészeket (vagy akár
teljes állományokat) akarunk bemutatni az
olvasónak, akkor érdemes ezeket egy
programlisting
elembe illeszteni.
A programlisting
elemeken belül
alkalmazott tördelés és a
sortörések helye jelentéssel
bír. Ennek egyik fontos
következménye, hogy a
nyitócímkének az állomány
tartalmának első sorával együtt kell
megjelennie, illetve a
zárócímkének pedig az
utolsó sorban, ellenkező esetben üres sorok
fognak keletkezni a kimenetben.
programlisting
elemA használat módja:
<para>Miután befejeztük a feladatot, a programunknak valahogy így kell majd kinéznie:</para> <programlisting>#include <stdio.h> int main(void) { printf("Halló mindenki!\n"); }</programlisting>
Láthatjuk, hogy az #include
után a relációs jeleket nem
közvetlenül adtuk meg, hanem a nekik
megfelelő egyedekkel.
Így jelenik meg:
Miután befejeztük a feladatot, a programunknak valahogy így kell majd kinéznie:
#include <stdio.h> int main(void) { printf("Halló mindenki!\n"); }
A magyarázó szövegek használatával a szöveg egy korábbi részére vagy egy korábbi példa adott helyére tudunk visszahivatkozni anélkül, hogy a szövegen magán belül hivatkoznánk rá.
Ehhez a co
elem
használatával jelöljük be a példa
(programlisting
,
literallayout
vagy bármi más)
fontosabb részeit. Mindegyik elemhez egy egyedi
azonosítót kell társítanunk. A
példa után helyezzünk el egy
calloutlist
elemet, amelyben a
megfelelő további magyarázat
megadásával együtt visszahivatkozunk a
példa egyes részeire.
co
és
calloutlist
elemek<para>Miután befejeztük a feladatot, a programunknak valahogy így kell majd kinéznie:</para> <programlisting>#include <stdio.h> <co id="co-ex-include"/> int <co id="co-ex-return"/> main(void) { printf("Halló mindenki!\n"); <co id="co-ex-printf"/> }</programlisting> <calloutlist> <callout arearefs="co-ex-include"> <para>A szabványos állományműveleteket tartalmazó header állomány.</para> </callout> <callout arearefs="co-ex-return"> <para>Megadjuk, hogy a <function>main()</function> függvény egy <literal>int</literal> típusú értékkel térjen vissza.</para> </callout> <callout arearefs="co-ex-printf"> <para>A <function>printf()</function> hívással egy <literal>Halló mindenki!</literal> szöveget írunk ki a szabványos kimenetre.</para> </callout> </calloutlist>
Így jelenik meg:
Miután befejeztük a feladatot, a programunknak valahogy így kell majd kinéznie:
#include <stdio.h>int
main(void) { printf("Halló mindenki!\n");
}
A HTML kapcsán megismertektől eltérően a szöveg elrendezésének befolyásolásához nem kell táblázatokat használnunk, mivel erről majd a stíluslapok gondoskodnak helyettünk. Ehelyett egyszerűen csak akkor használjunk táblázatokat, amikor táblázatosan akarunk adatokat megadni.
Általános értelemben véve
(ennek további részleteit lásd a DocBook
leírásában) a táblázatok
(amelyek lehetnek formálisak vagy informálisak)
egy table
elemből állnak.
Ennek magában kell foglalnia legalább egy
csoportot jelölő tgroup
elemet,
amely (tulajdonságként) megadja, hogy benne
mennyi oszlop található. Ezekben a csoportokban
aztán a thead
elemmel
fejlécet adhatunk meg az egyes oszlopoknak, illetve
azok törzseit pedig tbody
elemek
specifikálják.
A tgroup
és
thead
elemek egyaránt tartalmaznak
row
elemeket, amelyek pedig
entry
elemekre bonthatóak
tovább. Mindegyik ilyen entry
elem
a táblázat egy celláját
jelöli.
informaltable
elemA használat módja:
<informaltable pgwide="1"> <tgroup cols="2"> <thead> <row> <entry>Ez az első oszlop fejléce</entry> <entry>Ez a második oszlop fejléce</entry> </row> </thead> <tbody> <row> <entry>Első oszlop, első sor</entry> <entry>Második oszlop, első sor</entry> </row> <row> <entry>Első oszlop, második sor</entry> <entry>Második oszlop, második sor</entry> </row> </tbody> </tgroup> </informaltable>
Így jelenik meg:
Ez az első oszlop fejléce | Ez a második oszlop fejléce |
---|---|
Első oszlop, első sor | Második oszlop, első sor |
Első oszlop, második sor | Második oszlop, második sor |
Az informaltable
elemek esetén a
pgwide
tulajdonságot mindig az
1
értékkel használjuk,
ellenkező esetben az Internet Explorer egyik
hibája miatt a táblázat nem fog rendesen
megjelenni.
Amennyiben nem szeretnénk keretet a
táblázathoz, állítsuk az
informaltable
elem frame
tulajdonságát a none
értékre (vagyis <informaltable
frame="none">
).
frame="none"
típusú
táblázatÍgy jelenik meg:
Ez az első oszlop fejléce | Ez a második oszlop fejléce |
---|---|
Első oszlop, első sor | Második oszlop, első sor |
Első oszlop, második sor | Második oszlop, második sor |
Rengetegszer előfordulhat, hogy az olvasónak valamilyen módon be kell mutatnunk miként kell egy bizonyos feladatot megoldania a rendszerben. Ezek a példák általában valamilyen párbeszédet jelentek a számítógéppel: az olvasó begépel egy parancsot, amelyre kap egy választ, majd begépel egy újabb parancsot és így tovább.
Ilyen helyzetek több különböző elem és egyed alkalmazható.
screen
elemAz olvasó a példával
kapcsolatos információkat a elsősorban
képernyőről kapja, ennek
jelölésére használjuk a
screen
elemet.
A screen
elemeken belül
számít a szöveg
tördelése.
prompt
elem,
&prompt.root;
és
&prompt.user;
egyedekAz olvasó a képernyőn mindig
valamilyen promptot is látni fog (ez lehet az
operációs rendszer, a
parancsértelmező vagy az adott
alkalmazás). Ezt a prompt
elemmel tudjuk jelölni.
Az egyszerű felhasználó és
a rendszergazda számára két
külön egyed létezik a parancssori
promptok jelölésére. Amikor
tehát az olvasónak egy paranccsorban kell
tevékenykednie, akkor a
&prompt.root;
vagy a
&prompt.user;
egyedek
valamelyikét használjuk. Ezeket nem kell
prompt
elembe tenni.
A &prompt.root;
és
&prompt.user;
egyedek nem
részei az eredeti DocBook DTD-nek,
csupán a FreeBSD kiterjesztései.
userinput
elemA példában az olvasó
által begépelendő részeket
tegyük userinput
elemekbe. Ez
az olvasó felé
valószínűleg majd
másképpen jelenik meg.
screen
, prompt
és userinput
elemekA használat módja:
<screen>&prompt.user; <userinput>ls -1</userinput> ize1 ize2 ize3 &prompt.user; <userinput>ls -1 | grep ize2</userinput> ize2 &prompt.user; <userinput>su</userinput> <prompt>Password: </prompt> &prompt.root; <userinput>cat ize2</userinput> Ez lenne az 'ize2' nevű állomány.</screen>
Így jelenik meg:
%
ls -1
ize1 ize2 ize3%
ls -1 | grep ize2
ize2%
su
Password:
#
cat ize2
Ez lenne az 'ize2' nevű állomány.
Annak ellenére, hogy a példában
szerepeltettük az ize2
állomány tartalmát,
nem a programlisting
elemmel jelöltük. A
programlisting
elemeket inkább
állományrészletek
jelölésében alkalmazzuk,
függetlenül az olvasó
részéről várt
műveletektől.
Az egyes szavak vagy kifejezések
kiemeléséhez alkalmazzuk az
emphasis
elemet. Ennek
hatására a kiemelt szövegrész
dőlten, esetleg félkövéren jelenik
meg, illetve a különböző felolvasó
szoftverek más hangsúlyozással
mondják el.
A kiemelt szövegrészek tényleges
megjelenését nem tudjuk befolyásolni, nem
tekinthető egyenlőnek a HTML b
és i
elemeivel. Ha fontos
információt kívánunk
közölni, akkor az emphasis
helyett érdemesebb inkább az
important
elem használatát
megfontolni.
emphasis
elemA használat módja:
<para>A FreeBSD az Intel architektúrán kétség kívül <emphasis>a</emphasis> legjobb UNIX-szerű operációs rendszer.</para>
Így jelenik meg:
A FreeBSD az Intel architektúrán kétség kívül a legjobb UNIX-szerű operációs rendszer.
Ha más dokumentumokból vagy
forrásból akarunk idézni a szövegben,
esetleg valamire csak képletesen szeretnénk
utalni, akkor használjuk a quote
elemet. A quote
elemen belül a
legtöbb jelölő elérhető a
szövegben.
A használat módja:
<para>Arra viszont ügyeljünk, hogy hogy a keresési rend ne lépje át a <quote>helyi és nyilvános adminisztráció között meghúzódó határt</quote>, ahogy azt az RFC 1535 nevezi.</para>
Így jelenik meg:
Arra viszont ügyeljünk, hogy hogy a keresési rend ne lépje át a „helyi és nyilvános adminisztráció között meghúzódó határt”, ahogy azt az RFC 1535 nevezi.
A billentyűzeten egy adott billentyűre a
keycap
elem
segítségével tudunk hivatkozni. Ugyanezt
a lehetőséget az egér gombjaira
vonatkozóan a mousebutton
elem
nyújta. A billentyűk és egérgombok
együttes használatát pedig a
keycombo
elemmel tudjuk
jelölni.
A keycombo
elemnek van egy
action
(tevékenység)
nevű tulajdonsága, amely lehet
click
(kattintás),
double-click
(kettős
kattintás), other
(egyéb),
press
(nyomva tartás),
seq
(egymás utáni), illetve
simul
(együttes használat). Az
utóbbi két értékkel
jelölhetjük, hogy a megadott billentyűket vagy
gombokat egymás után esetleg egyszerre kell
lenyomnunk.
Az elemben felsorolt billentyűk és gombok
nevei közé a stíluslapok automatikusan
beillesztik a megfelelő összekapcsoló
szimbólumot, például a
+
jelet.
A használat módja:
<para>A második virtuális terminálra az <keycombo action="simul"><keycap>Alt</keycap><keycap>F1</keycap></keycombo> billentyűkombinációval tudunk átváltani.</para> <para>A <command>vi</command> programból úgy tudunk mentés nélkül kilépni, ha begépeljük a <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap> <keycap>q</keycap><keycap>!</keycap></keycombo> sorozatot.</para> <para>Az ablakkezelőt most úgy állítottuk be, hogy az <keycombo action="simul"><keycap>Alt</keycap> <mousebutton>jobb</mousebutton></keycombo> egérgomb segítségével tudjuk mozgatni az ablakokat.</para>
Így jelenik meg:
A második virtuális terminálra az Alt+F1 billentyűkombinációval tudunk átváltani.
A vi
programból úgy
tudunk mentés nélkül kilépni, ha
begépeljük az Esc : q !
sorozatot.
Az ablakkezelőt most úgy állítottuk be, hogy az Alt+ egyérgomb segítségével tudjuk mozgatni az ablakokat.
Nem szokatlan az igény, hogy a dokumentáció írása során gyakran szeretnénk hivatkozni alkalmazásokra és parancsokra egyaránt. A két fajta elem közti különbség egyszerű: az alkalmazás az adott feladatot megvalósító programcsomag (vagy program) neve, miközben a parancs konkrétan annak a programnak a neve, amelyet az olvasó futtatni tud.
Mindezek mellett alkalmanként szükségünk lehet arra, hogy a parancs által várt egy vagy több paramétert valamilyen módon felsoroljuk.
Végül hozzátesszük, hogy sokszor szükségünk lehet a parancsokat a hozzájuk tartozó man oldalakkal együtt hivatkozni, a UNIX típusú kézikönyvek megszokott „parancs(szám)” jelölésben.
Az alkalmazások neveit az
application
elemmel tudjuk
jelölni.
Ha egy parancsot a hozzá tartozó man oldallal
együtt akarunk hivatkozni (amire
valószínűleg az esetek nagy
többségében szükségünk is
lesz), akkor az ennek megfelelő Docbook elem a
citerefentry
lesz. Ez további
két elemet tartalmaz, ezek a
refentrytitle
és a
manvolnum
. A
refentrytitle
tartalma a parancs neve,
illetve a manvolnum
lesz a
hozzá tartozó man oldal megfelelő
szekciója.
Az iménti jelölések írása
esetenként nehézkesnek bizonyulhat, ezért
ennek megkönnyítésére
létrehoztunk általános egyedeket.
Az egyedek
&man.man-oldal.man-szekció;
alakban érhetőek el.
Ezeket az egyedeket a
doc/share/xml/man-refs.ent
állományban találjuk meg, amelyre a
következő formális publikus
azonosító segítségével
tudunk hivatkozni:
PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"
Ezért tehát a dokumentumunk elején minden bizonnyal szerepelni fog egy ilyen sor:
<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> %man; … ]>
A command
elemmel a parancsok neveit
tudjuk a szövegben hivatkozni közvetlenül, az
olvasó által begépelendő
formában.
Az option
elem
segítségével a parancsok
számára megadható kapcsolókat
jelölhetjük.
Amikor többször ugyanarra a parancsra
hivatkozunk egymáshoz viszonylag közel, a
&man.parancs.szekció;
típusú jelölést érdemes csak
az első hivatkozásnál alkalmazni, a
többi inkább legyen egyszerűen csak
command
elemben. Az ebből
készített kimenet, különösen a
HTML esetében így kinézetében
sokkal olvashatóbb.
A jelölési megoldások közti választás ettől függetlenül időnként nem mindig egyértelmű, de remélhetőleg a következő példa segít ebben.
A használat módja:
<para>A <application>sendmail</application> az egyik legelterjedtebb levelező alkalmazás UNIX rendszereken.</para> <para>A <application>sendmail</application> alkalmazás részei a <citerefentry> <refentrytitle>sendmail</refentrytitle> <manvolnum>8</manvolnum> </citerefentry>, &man.mailq.1; és &man.newaliases.1; programok.</para> <para>A <citerefentry> <refentrytitle>sendmail</refentrytitle> <manvolnum>8</manvolnum> </citerefentry> egyik kapcsolója a <option>-bp</option>, amellyel a levelezési sorban található üzenetek aktuális állapotát kérdezhetjük le. Ezt a <command>sendmail -bp</command> parancs kiadásával tehetjük meg.</para>
Így jelenik meg:
A sendmail az egyik legelterjedtebb levelező alkalmazás UNIX rendszereken.
A sendmail alkalmazás részei a sendmail(8), mailq(1) és newaliases(1) programok.
A sendmail(8) egyik kapcsolója a
-bp
, amellyel a levelezési sorban
található üzenetek aktuális
állapotát kérdezhetjük le. Ezt a
sendmail -bp
parancs
kiadásával tehetjük meg.
Figyeljük meg, hogy a
&man.parancs.szekció;
jelölés mennyivel könnyebben
olvasható.
Amikor állományok neveire,
könyvtárakra, esetleg kiterjesztésekre
akarunk hivatkozni, használjunk a
filename
elemeket.
filename
elemA használat módja:
<para>A kézikönyv magyar változatának SGML forrása a <filename class="directory">/usr/doc/hu_HU.ISO8859-2/books/handbook/</filename> könyvtárban található. Ebben a könyvtárban a <filename>book.xml</filename> lesz a fő forrásállomány. Mellette láthatunk még egy <filename>Makefile</filename> állományt és több <filename>.ent</filename> kiterjesztéssel rendelkező állományt.</para>
Így jelenik meg:
A kézikönyv magyar
változatának SGML forrása a /usr/doc/hu_HU.ISO8859-2/books/handbook
könyvtárban található. Ebben a
könyvtárban a book.xml
lesz
a fő forrásállomány. Mellette
találhatunk még egy
Makefile
állományt
és több .ent
kiterjesztéssel rendelkező
állományt.
Ezek az elemek a FreeBSD DocBookhoz készített kiterjesztéseinek részei, az eredeti DocBook DTD-ben nem szerepelnek.
Esetenként szükségünk lehet a FreeBSD
Portgyűjteményében található
bizonyos programok nevének
megemlítésére a
dokumentációban. Ezt a
filename
elem role
tulajdonságának a package
értékre állításával
tehetjük meg. Mivel a Portgyűjtemény
tetszőleges helyre telepíthető, ezért
mindig csak a port kategóriáját és
nevét adjuk meg, a /usr/ports
rész elhagyásával.
filename
elem és a
package
role együttes
használataA használat módja:
<para>A hálózati forgalom figyeléséhez telepítsük a <filename role="package">net/ethereal</filename> portot.</para>
Így jelenik meg:
A hálózati forgalom figyeléséhez telepítsük a net/ethereal portot.
Ezek az elemek a FreeBSD DocBookhoz készített kiterjesztéseinek részei, az eredeti DocBook DTD-ben nem szerepelnek.
Az eszközök hivatkozását
két módon jelölhetjük. Az eszközre
hivatkozhatunk a /dev
könyvtárban megjelenő neve szerint, vagy
pedig a rendszermagbeli neve szerint. Ez utóbbi
esetben használjuk a devicename
jelölést.
Néha előfordulhat, hogy nincs
választási lehetőségünk.
Bizonyos eszközök, például a
hálózati kártyákhoz nem tartozik
semmilyen bejegyzés a /dev
könyvtárban, esetleg az ott megjelenő
nevük teljesen eltér.
devicename
elemA használat módja:
<para>A FreeBSD rendszermagjában a <devicename>sio</devicename> eszközöket a soros vonali kommunikációra használjuk. A <devicename>sio</devicename> eszközök az idők során több különböző alakban jelentek meg a <filename>/dev</filename> könyvtárban, például <filename>/dev/ttyd0</filename> és <filename>/dev/cuaa0</filename> néven.</para> <para>Ezzel szemben a hálózati eszközök, mint például az <devicename>ed0</devicename> nem jelennek meg a <filename>/dev</filename> könyvtárban.</para> <para>Az MS-DOS rendszerekben az elsődleges hajlékonylemezes meghajtót az <devicename>a:</devicename> néven érhetjük el, miközben FreeBSD alatt ennek a neve <filename>/dev/fd0</filename>.</para>
Így jelenik meg:
A FreeBSD rendszermagjában a
sio
eszközöket a soros
vonali kommunikációra használjuk. A
sio
eszközök az idők
során több különböző alakban
jelentek meg a /dev
könyvtárban, például
/dev/ttyd0
és
/dev/cuaa0
néven.
Ezzel szemben a hálózati
eszközök, mint például az
ed0
nem jelennek meg a
/dev
könyvtárban.
Az MS-DOS rendszerekben az elsődleges
hajlékonylemezes meghajtót az
a:
néven
érhetjük el, miközben FreeBSD alatt ennek a
neve /dev/fd0
.
Ezek az elemek a FreeBSD DocBookhoz készített kiterjesztéseinek részei, az eredeti DocBook DTD-ben nem szerepelnek.
A vonatkozó információ
jellegétől függően a
hálózatba kapcsolt
számítógépek
azonosítására szolgáló
adatatokat többféle módon is jelölni
tudjuk. Minden esetben a hostid
elemre
fogunk támaszkodni, amely role
tulajdonságával tudjuk megválasztani a
jelölt információ
típusát.
role
tulajdonság vagy
role="hostname"
A role
tulajdonság
megadása nélkül (vagyis az elem
hostid
…/hostid
alakú) a jelölt információ egy
hálózati név, mint
például freefall
vagy
disznohal
. Ugyanezt explicit
módon a role="hostname"
hozzáadásával tudjuk
jelölni.
role="domainname"
Az elem tartalma egy tartomány nevét
jelöli, mint például
FreeBSD.org
vagy
inf.elte.hu
. Ekkor nincs benne
konkrét hálózati név.
role="fqdn"
Az elem tartalma egy teljes hálózati név, amely már tartalmaz tartománynevet és hálózati nevet.
role="ipaddr"
Az elem egy IP-címet jelöl, négy, pontokkal tagolt szám formájában.
role="ip6addr"
Az elem egy IPv6 formátumú IP-címet jelöl.
role="netmask"
Az elem tartalma egy hálózati maszk,
amelyet megadhatunk pontokkal elválasztott
számokkal, hexadecimális
számjegyekkel vagy a /
szimbólumot követően egy
számmal.
role="mac"
Az elemben egy Ethernet MAC-címet adtunk meg, kétjegyű hexadecimális számok kettőspontokkal tagolt sorozataként.
hostid
elem és a
különböző role
értékekA használat módja:
<para>A gépünk mindig elérhető <hostid>localhost</hostid> néven, amelyhez a <hostid role="ipaddr">127.0.0.1</hostid> IP-cím tartozik.</para> <para>A <hostid role="domainname">FreeBSD.org</hostid> tartomány több különböző gépet foglal magában, többek közt a <hostid role="fqdn">freefall.FreeBSD.org</hostid> és <hostid role="fqdn">pointyhat.FreeBSD.org</hostid> címeket.</para> <para>Amikor egy interfészhez IP-álnéveket társítunk (az <command>ifconfig</command> paranccsal), akkor ehhez <emphasis>mindig</emphasis> a <hostid role="netmask">255.255.255.255</hostid> hálózati maszkot adjuk meg (amelyet <hostid role="netmask">0xffffffff</hostid> formában is írhatunk).</para> <para>A MAC-cím az összes létező hálózati eszközt egyértelműen azonosítja. A MAC-címek általában a <hostid role="mac">08:00:20:87:ef:d0</hostid> címhez hasonlóak.</para>
Így jelenik meg:
A gépünk mindig elérhető
localhost
néven, amelyhez a 127.0.0.1
IP-cím tartozik.
A FreeBSD.org
tartomány több különböző
gépet foglal magában, többek közt a
freefall.FreeBSD.org
és
pointyhat.FreeBSD.org
címeket.
Amikor egy interfészhez
IP-álnéveket társítunk (az
ifconfig
paranccsal), akkor ehhez
mindig a 255.255.255.255
hálózati maszkot adjuk meg (amelyet 0xffffffff
formában is
írhatunk).
A MAC-cím az összes létező
hálózati eszközt egyértelműen
azonosítja. A MAC-címek
általában a 08:00:20:87:ef:d0
címhez
hasonlóak.
Ezek az elemek a FreeBSD DocBookhoz készített kiterjesztéseinek részei, az eredeti DocBook DTD-ben nem szerepelnek.
Ha felhasználókra (például
root
vagy bin
) kell
hivatkoznunk a szövegben, használjuk a
username
elemet.
username
elemA felhasználás módja:
<para>A rendszerünk karbantartásával kapcsolatos legtöbb feladatot kizárólag csak a <username>root</username> felhasználóval tudjuk elvégezni.</para>
Így jelenik meg:
A rendszerünk karbantartásával
kapcsolatos legtöbb feladatot kizárólag
csak a root
felhasználóval tudjuk elvégezni.
Ezek az elemek a FreeBSD DocBookhoz készített kiterjesztéseinek részei, az eredeti DocBook DTD-ben nem szerepelnek.
A Makefile
állományok
egyes részeinek jelöléséhez a
maketarget
és
makevar
elemeket tudjuk
használni.
A maketarget
azokat a
Makefile
állományokban
megadott fordítási célokat
azonosítja, amelyeket a make
paramétereként lehet használni. A
makevar
pedig azokat a (környezetben,
a make
hívásakor vagy a
Makefile
állományon
belül definiált) változókat
azonosítja, amelyekkel a fordítás
folyamát lehet szabályozni.
maketarget
és a
makevar
elemekA használat módja:
<para>A <filename>Makefile</filename> állományokban két igen gyakori cél az <maketarget>all</maketarget> és a <maketarget>clean</maketarget>.</para> <para>Az <maketarget>all</maketarget> megadásakor általában újrafordítjuk az alkalmazást, a <maketarget>clean</maketarget> megadásakor pedig eltávolítjuk a fordítás közben keletkezett ideiglenes állományokat (például az <filename>.o</filename> állományokat).</para> <para>A <maketarget>clean</maketarget> viselkedését számos változó befolyásolja, többek közt a <makevar>CLOBBER</makevar> és a <makevar>RECURSE</makevar>.</para>
Így jelenik meg:
A Makefile
állományokban két igen gyakori
cél az all
és a
clean
.
Az all
megadásakor
általában újrafordítjuk az
alkalmazást, a clean
megadásakor pedig eltávolítjuk a
fordítás közben keletkezett ideiglenes
állományokat (például az
.o
állományokat).
A clean
viselkedését számos változó
befolyásolja, többek közt a
CLOBBER
és a
RECURSE
.
Sokszor lehet szükségünk „formázatlan” szövegekre a dokumentáció írása közben. Ilyen szöveg jellemző módon egy valamelyik másik állományból átvett részlet, vagy amelyet magából a dokumentációból kell szó szerint átmásolni egy állományba.
Néhány esetben a korábban már
bemutatott programlisting
pontosan
elegendő ehhez a feladathoz. Azonban ez a
jelölési módszer nem minden esetben
megfelelő, különösen olyan helyzetekben,
amikor az állomány egy részét
magába a bekezdésbe akarjuk tenni.
Ilyen alkalmakkor használjuk a
literal
elemet.
literal
elemA használat módja:
<para>A rendszermag konfigurációs állományában a <literal>maxusers 10</literal> sor határozza meg különböző rendszerszintű táblázatok méretét, és ezáltal ad egy durva becslést arra, hogy a rendszerünk mennyi bejelentkezést lesz képes egyszerre kezelni.</para>
Így jelenik meg:
A rendszermag konfigurációs
állományában a maxusers 10
sor határozza meg különböző
rendszerszintű táblázatok
méretét, és ezáltal ad egy durva
becslést arra, hogy a rendszerünk mennyi
bejelentkezést lesz képes egyszerre
kezelni.
Minden bizonnyal lesznek olyan részek a dokumentációban, ahol meg szeretnénk mutatni az olvasónak mit kell csinálnia, esetleg hivatkozni akarunk egy állomány nevére vagy egy parancsra stb., viszont nem közvetlenül a megadott nevet kell bemásolnia, hanem önmagától kell kipótolnia egy sémát.
Pontosan ilyen eshetőségekre
találták ki a replaceable
elemet. Más elemeken belül
használva olyan részeket tudunk vele
megjelölni, amelyeket az olvasónak kell
kitöltenie.
replaceable
elemA használat módja:
<screen>&prompt.user; <userinput>man <replaceable>parancs</replaceable></userinput></screen>
Így jelenik meg:
%
man parancs
A replaceable
több
különböző elemen belül is
alkalmazható, egyik ilyen a
literal
. Ebben a példában
azt is megmutatjuk, hogy a replaceable
elembe ténylegesen csak azt a részt kell
tennünk, amelyet az
olvasónak kell hozzátennie, rajta
kívül semmi mást nem kell
megváltoztatnia.
A használat módja:
<para>A rendszermag konfigurációs állományában a <literal>maxusers <replaceable>n</replaceable></literal> sor határozza
meg különböző rendszerszintű táblázatok méretét, és ezáltal ad egy
durva becslést arra, hogy a rendszerünk mennyi bejelentkezést
lesz képes egyszerre kezelni.</para>
<para>Asztali munkaállomások esetén az n
helyére írhatjuk például a <literal>32</literal>
értéket.</para>
Így jelenik meg:
A rendszermag konfigurációs
állományában a maxusers
n
sor határozza meg különböző
rendszerszintű táblázatok
méretét, és ezáltal ad egy durva
becslést arra, hogy a rendszerünk mennyi
bejelentkezést lesz képes egyszerre
kezelni.
Asztali munkaállomások esetén az
n
helyére írhatjuk
például a 32
értéket.
A dokumentációban a képek használatának támogatása jelen pillanatban még csak kísérleti jellegű. Az itt leírt ismeretek valószínűleg nem fognak változni, de nem szavatoljuk.
A különféle képformátumok
közti átalakításokhoz még
telepítenünk kell a graphics/ImageMagick portot. Ez egy
nagy méretű port és a legtöbb
részére nincs is konkrétan
szükségünk, viszont jelentősen meg tudja
könnyíteni a dolgunkat, amikor
Makefile
állományokkal
és egyéb infrastrukturális elemekkel
dolgozunk. Ez a port nem része a
textproc/docproj
metaportnak, külön kell egyedileg
telepítenünk.
A képek használatára talán a
legjobb példát a
doc/en_US.ISO8859-1/articles/vm-design
szolgáltatja. Ha tehát nem
értenénk teljesen a szakaszban leírtakat,
nézzük meg ezt az állományt
és a gyakorlatban is látni fogjuk hogyan
kapcsolódnak össze az felhasznált elemek.
Ne restelljünk kísérletezgetni a
különböző formázási
stílusokkal, így láthatjuk miként
jelennek meg a jelölt képek a formázott
kimenetben.
Jelenleg kétféle képformátum támogatott. A beillesztendő kép jellegétől függ, hogy ezek közül ténylegesen melyiket kell majd használnunk a dokumentumban.
Az alapvetően vektoros szerkezetű
képeket, mint például a
hálózati kapcsolatokat bemutató
diagramokat, idővonalakat és ehhez
hasonlókat Encapsulated Postscript formátumban
érdemes ábrázolnunk. Gondoskodjunk
róla, hogy ezek a képek
.eps
kiterjesztéssel
rendelkezzenek.
A raszteres képeket, mint például a
képernyő elmentett tartalmát Portable Network
Graphic formátumban készítsük el.
Figyeljünk rá, hogy az ilyen típusú
képek kiterjesztése mindig
.png
legyen.
Ezek tehát kizárólagosan azok a formátumok, amelyek bekerülhetnek a repositoryba.
A képekhez mindig válasszuk a megfelelő
formátumot, teljesen elfogadott a
dokumentációban az EPS és PNG
formátumú képek vegyes
alkalmazása. A Makefile
állományok gondoskodni fognak a képek
formátumuknak megfelelő szabályos
feldolgozásáról. Ugyanazt a
képet a repositoryban ne tároljuk el mind a
két formátumban!
A Dokumentációs Projekt előreláthatólag a jövőben majd a vektoros képek ábrázolására a Scalable Vector Graphic (SVG) formátumot fogja használni, azonban jelenleg még nem állnak rendelkezésre olyan SVG szerkesztők, amelyek ezt a gyakorlatban is hatékonnyá tennék.
A képek jelölése viszonylag
egyszerű. Először is
készítsünk egy
mediaobject
elemet. A
mediaobject
elembe ezután
további, pontosabban specifikáló
objektumokat helyezhetünk el. Most két ilyen
elemmel foglakozunk, ezek az imageobject
és a textobject
.
Egy imageobject
és két
textobject
elemet kell megadnunk. Az
imageobject
a beilleszteni
kívánt kép nevére fog hivatkozni
(kiterjesztés nélkül). A
textobject
elemekben olyan
információ szerepel, amelyet az olvasó a
kép mellett vagy éppen helyett fog látni
a dokumentumban.
Ilyen két esetben fordulat elő:
A dokumentum HTML változatát olvassuk. Ekkor minden képhez szükség van még egy helyettesítő szövegre, amelyet a kép betöltődésekor láthatunk, vagy amikor az egérmutatót a kép felé visszük.
A dokumentumot nyers szöveges formátumban olvassuk. Ekkor a kép ASCII karakterekből kirakott változatát kellene látnia az olvasónak.
Egy példán keresztül mindez
valószínűleg sokkal könnyebben
érthetővé válik. Tegyük
tehát most fel, hogy van egy abra1.png
nevű képünk, amelyet szeretnénk
betenni a dokumentumba. Ez a kép egy A betűt
ábrázol egy téglalapban. A
hozzá tartozó jelölés a
következő lesz:
<mediaobject> <imageobject> <imagedata fileref="abra1"></imageobject> <textobject> <literallayout class="monospaced">+---------------+
| A | +---------------+</literallayout> </textobject> <textobject> <phrase>Egy kép</phrase>
</textobject> </mediaobject>
Helyezzünk el egy | |
Az első A | |
A második |
A Makefile
állományokban az IMAGES
változóban kell felsorolnunk a dokumentumhoz
tartozó képeket. Ebben a
változóban kell megadnunk a képek
forrását. Tehát
például, ha van három
ábránk, név szerint az
abra1.eps
, abra2.png
és abra3.png
, akkor ennek
megfelelően a Makefile
állománynak a következő sorokat
kellene tartalmaznia:
… IMAGES= abra1.eps abra2.png abra3.png …
vagy
… IMAGES= abra1.eps IMAGES+= abra2.png IMAGES+= abra3.png …
A Makefile
magától el
fogja készíteni a dokumentum
lefordításához szükséges
képek teljes listáját, nekünk
egyedül tehát csak azokat a képeket kell
megadnunk, amelyeket mi
készítettünk.
Nem árt óvatosnak lennünk, amikor a dokumentumunkat kisebb állományokra bontjuk szét (lásd 3.7.1. szakasz - Állományok tartalmának elérése általános egyedekkel) több különböző alkönyvtárban.
Tegyük fel, hogy van egy három fejezetből
álló könyvünk, ahol az egyes fejezeteket
a saját könyvtáraikban tároljuk:
fejezet1/fejezet.xml
,
fejezet2/fejezet.xml
és
fejezet3/fejezet.xml
. Ha az egyes
fejezetekhez képeket akartunk társítani,
akkor javasolt ezeket a fejezetek
alkönyvtárába
(fejezet1
, fejezet2
,
fejezet3
) tennünk.
Ekkor azonban ne felejtsük el, hogy a
Makefile
állomány
IMAGES
változójában
és az imagedata
elemekben is a könyvtárak neveivel együtt
kell hivatkoznunk a képekre.
Például a
fejezet1/abra.png
kép
esetében a fejezet1/fejezet.xml
állományban a következőt kell
megadnunk:
<mediaobject> <imageobject> <imagedata fileref="fejezet1/abra1"></imageobject> … </mediaobject>
Az ennek megfelelő Makefile
állomány tartalma:
… IMAGES= fejezet1/fejezet1.png …
Ezzel már minden remekül működik.
A hivatkozások is belső elemek.
A dokumentum belül úgy tudunk hivatkozásokat készíteni, ha egyrészt megadjuk honnan hivatkozunk (tehát szükségünk lesz egy olyan elemre, amelyre az olvasó kattinthat vagy megjelölhető a hivatkozás forrásaként), másrészt megadjuk hova hivatkozunk (tehát a célt).
A DocBook összes eleme rendelkezik egy
id
tulajdonsággal, amelyben az adott
elem adott példányához tudunk kapcsolni
egy egyedi azonosítót.
Ezt az értéket kell megadnunk a hivatkozás forrásának megjelölésekor.
Általában tehát amikor fejezeteket
vagy szakaszokat hivatkozunk, érdemes felvennünk
hozzájuk egy id
tulajdonságot.
id
tulajdonság
fejezeteknél és szakaszoknál<chapter id="fejezet"> <title>Bevezetés</title> <para>Ez a bevezetés. Ebben szerepel egy szintén azonosítóval rendelkező alszakasz.</para> <sect1 id="fejezet1-szakasz1"> <title>Első alszakasz</title> <para>Ez az alszakasz.</para> </sect1> </chapter>
A dokumentáció írásakor
nyilván ennél beszédesebb
azonosítókat lesz majd érdemes
kitalálnunk. Mindig ügyeljünk arra, hogy az
azonosítóknak egyedieknek kell lenniük a
dokumentumban (tehát nem csak az adott
állományon, hanem a teljes dokumentum
belül). Figyeljük meg hogyan képeztük a
példában az alszakasz id
tulajdonságát a fejezet id
tulajdonságának
értékéből. Ezzel szavatoltuk az
azonosító egyediségét.
Ha a dokumentum valamelyik közbenső
elemére (jellemzően egy bekezdés vagy egy
példa közepére) akarunk hivatkozni, akkor
használjuk az anchor
elemet. Ennek
az elemnek nincs tartalma, azonban rendelkezik
id
tulajdonsággal.
anchor
elem<para>Ebben a bekezdésben elrejtettünk egy <anchor id="bekezd">hivatkozás forrását. Ez a dokumentumban nem fog látszani.</para>
Ha a dokumentum egy id
tulajdonsággal rendelkező részére
szeretnénk létrehozni egy hivatkozást
(amelyet például kattintással el lehet
érni), akkor használjuk az
xref
vagy link
elemeket.
Mind a két imént említett elemnek van
egy linkend
tulajdonsága. Ennek az
értéke lényegében ugyanaz lesz,
amelyet a hivatkozás forrásában az
id
tulajdonság
értékének megadtunk (nem
számít, hogy ez szerepelt-e már a
dokumentumban a hivatkozás helye előtt, mert
előre és visszafele is lehet hivatkozni).
Az xref
elem használatakor a
hivatkozás szövege magától jön
létre, nem tudjuk befolyásolni.
xref
elemTegyük fel, hogy felbukkan a következő
szövegrészlet valahol a dokumentumban, amely
hivatkozik a korábbi id
tulajdonságot bemutató példánk
azonosítóira:
<para>A témával kapcsolatos részleteket az <xref linkend="fejezet1"> foglalja össze.</para> <para>További részleteket pedig a <xref linkend="fejezet1-szakasz1"> tár fel.</para>
Ekkor tehát a hivatkozás szövege magától létrejön, így a következő szöveget kapjuk (a kiemelt rész jelzi a hivatkozás szövegét):
A témával kapcsolatos részleteket az Első fejezet foglalja össze.
További részleteket pedig az Első alszakasz tár fel.
Figyeljük meg hogyan képeződött a fejezet számából vagy a szakasz címéből a megfelelő hivatkozás.
Az iméntiekből következik, hogy az
xref
elemmel nem
lehet anchor
elemek
id
tulajdonságaira hivatkozni. Az
anchor
elemben nincs semmi, ezért
az xref
nem képes
magától létrehozni hozzá a
hivatkozás szövegét.
Ha szeretnénk kézzel megadni a
hivatkozások szövegét, akkor
használjuk a link
elemet, amelynek a
tartalmában szerepeltethetjük ezt.
link
elemTegyük fel, hogy a következő
szövegrészlet jelenik meg valahol a
dokumentumnkban, és az id
tulajdonságot bemutató példában
definiált azonosítókra
hivatkozik.
<para>Erről bővebb tájékoztatást <link linkend="fejezet1">az első fejezetben</link> kapunk.</para> <para>Erről a részről pedig <link linkend="fejezet1-szakasz1">ebben</link> a szakaszban olvashatunk többet.</para>
Ez a következőképpen jelenik meg (ahol a kiemelt szövegek jelzik a hivatkozásokat magukat):
Erről bővebb tájékoztatást az első fejezetben kapunk.
Erről a részről pedig ebben a szakaszban olvashatunk többet.
Ez utóbbi nem teljesen egy jó példa. Lehetőleg ne „ebben” vagy „itt” néven hivatkozzunk, mert az olvasó így nem fogja közvetlenül látni, hogy az adott hivatkozás pontosan hova is viszi.
A link
elemmel már
tudunk hivatkozni
anchor
elemek id
tulajdonságaira, hiszen a link
elemben már megadható a hivatkozás
szövege.
A külső dokumentumok hivatkozása
valamennyivel könnyebb a belső hivatkozások
használatánál, mivel ehhez csak annyit
kell tudunk, milyen címre akarunk mutatni. Erre az
ulink
elem alkalmas. Rendelkezik egy
url
tulajdonsággal, amelyben a
hivatkozni kívánt oldal címét kell
megadnunk. Az elem belsejében pedig a
hivatkozás olvasó felé megjelenő
szövegét adhatjuk meg.
ulink
elemA használat módja:
<para>Természetesen már most felhagyhatunk a dokumentum olvasásával és helyette megnézhetjük a <ulink url="&url.base;/index.html">FreeBSD honlapját</ulink>.</para>
Így jelenik meg:
Természetesen már most felhagyhatunk a dokumentum olvasásával és helyette megnézhetjük a FreeBSD honlapját.
[2] Ennek rövid története a http://www.oasis-open.org/docbook/intro.shtml#d0e41
címen olvasható.
[3] A felsorolások megadására a DocBook további lehetőségeket is felkínál, azonban ezekkel itt most nem foglalkozunk.
Ha kérdése van a FreeBSD-vel kapcsolatban, a
következő címre írhat (angolul):
<questions@FreeBSD.org>.
Ha ezzel a dokumentummal kapcsolatban van kérdése, kérjük erre a címre írjon:
<gabor@FreeBSD.org>.