4.2. DocBook

4.2.3.1. Könyv írása

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>
  <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>

4.2.3.2. Cikk írása

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>
  <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>

4.2.3.3. Fejezetek készítése

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.

<chapter>
  <title>Fejezetcím</title>

  ...
</chapter>

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.

<chapter>
  <title>Ez egy üres fejezet</title>

  <para></para>
</chapter>

4.2.3.4. Szakaszok fejezetek alatt

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 <sectn> elemet használhatjuk, ahol az n szám adja meg a szakasz szintjét.

Az első ilyen <sectn> elem a <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>

    &hellip;
  </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>

        &hellip;
      </sect3>
    </sect2>

    <sect2>
      <title>Második alszakasz (1.2.2)</title>

      &hellip;
    </sect2>
  </sect1>
</chapter>

4.2.3.5. A dokumentum felosztása <part> elemek használatával

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>

4.2.4.1. Bekezdések

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>Ez egy bekezdés.  Tetszőleges egyéb elem megjelenhet benne.</para>

4.2.4.2. Idézetblokkok

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).

<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>

4.2.4.3. Tanácsok, megjegyzések, felhívások, figyelmeztetések, fontos és mellékes információk

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>
  <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:

4.2.4.4. Felsorolások és eljárások

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[2].

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>
  <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>

4.2.4.5. Példák állományokra

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.

<para>Miután befejeztük a feladatot, a programunknak valahogy így kell
  majd kinéznie:</para>

<programlisting>#include &lt;stdio.h&gt;

int
main(void)
{
    printf("Halló mindenki!\n");
}</programlisting>

#include <stdio.h>

int
main(void)
{
    printf("Halló mindenki!\n");
}

4.2.4.6. Magyarázó szövegek

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.

<para>Miután befejeztük a feladatot, a programunknak valahogy így kell
  majd kinéznie:</para>

<programlisting>#include &lt;stdio.h&gt; <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>

#include <stdio.h> 

int 
main(void)
{
    printf("Halló mindenki!\n"); 
}

4.2.4.7. Táblázatok

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 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>

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">).

4.2.4.8. Példák műveletekre

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>&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>

% ls -1
ize1
ize2
ize3
% ls -1 | grep ize2
ize2
% su
Password: 
# cat ize2
Ez lenne az 'ize2' nevű állomány.

4.2.5.1. Az információ kiemelése

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.

<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>

4.2.5.2. Idézetek

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.

<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>

4.2.5.3. Billentyűk, egérgombok és azok kombinációja

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.

<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>

4.2.5.4. Alkalmazások, parancsok, kapcsolók és man hivatkozások

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.

<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>

4.2.5.5. Állományok, könyvtárak, kiterjesztések

Amikor állományok neveire, könyvtárakra, esetleg kiterjesztésekre akarunk hivatkozni, használjunk a <filename> elemeket.

<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>

4.2.5.6. A portok nevei

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.

<para>A hálózati forgalom figyeléséhez telepítsük a <filename
    role="package">net/ethereal</filename> portot.</para>

4.2.5.7. Eszközök

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.

<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>

4.2.5.8. Hálózati nevek, tartományok, IP-címek és így tovább

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.

<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>

4.2.5.9. Felhasználói nevek

Ha felhasználókra (például root vagy bin) kell hivatkoznunk a szövegben, használjuk a <username> elemet.

<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>

4.2.5.10. A Makefile állományokkal kapcsolatos jelölések

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.

<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>

4.2.5.11. Formázatlan szöveg

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.

<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>

4.2.5.12. Az olvasó által kötelezően kitöltendő részek jelölése

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.

<screen>&prompt.user; <userinput>man <replaceable>parancs</replaceable></userinput></screen>

% man parancs

<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>

4.2.5.13. Hibaüzenetek idézése

Olykor szükségünk lehet a FreeBSD által jelzett hibák jelölésére. A hibák során keletkező pontos hibaüzeneteket tegyük <errorname> elemekbe.

<screen><errorname>Panic: cannot mount root</errorname></screen>

“Panic: cannot mount root”

4.2.6.1. Képformátumok

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!

4.2.6.2. Jelölések

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 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>

4.2.6.3. A Makefile felépítése

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.

4.2.6.4. Képek és fejezetek alkönyvtárakban

Nem árt óvatosnak lennünk, amikor a dokumentumunkat kisebb állományokra bontjuk szét (lásd 3.7.1 Szakasz) 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.

4.2.7.1. Hivatkozás ugyazon a dokumentumon belül

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.

<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.

<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.

<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>

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.

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.

<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>

4.2.7.2. A Világhálón található dokumentumok hivatkozása

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.

<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>