A FreeBSD Dokumentációs Projekt irányelvei kezdőknek
Előző | Fejezet 4. Az SGML alkalmazása | Következő

# 4.2. DocBook

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[1], 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.

## 4.2.1. A FreeBSD kiterjesztései

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

> Megjegyzés: 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.

## 4.2.2. Formális publikus azonosító

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"

## 4.2.3. A dokumentum szerkezete

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.

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

Példa 4-21. Egy `<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>

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

Példa 4-22. Egy `<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>

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

Példa 4-23. Egy egyszerű fejezet

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

Példa 4-24. Üres fejezetek

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

Az első ilyen `<sect`n`>` 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.

Példa 4-25. Szakaszok fejezetekben

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

> Megjegyzés: 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.

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

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

Példa 4-26. A `<para>` elem

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

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

Példa 4-27. A `<blockquote>` elem

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

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

Példa 4-28. A `<warning>` elem

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

> Figyelem: A FreeBSD telepítése után könnyen előfordulhat, hogy a Windowst teljesen le akarjuk törölni a merevlemezünkről.

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

Példa 4-29. Az `<itemizedlist>`, `<orderedlist>` és `<procedure>` elemek

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

1. Ez az első sorszámozott elem.

2. Ez a második sorszámozott elem.

1. Csináljuk ezt.

2. Majd csináljuk azt.

3. Most pedig csináljuk így.

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

Példa 4-30. A `<programlisting>` elem

A használat módja:

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

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");
    }

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

Példa 4-31. A `<co>` és `<calloutlist>` elemek

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

Í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 szabványos állományműveleteket tartalmazó header állomány.
  Megadjuk, hogy a `main()` függvény egy `int` típusú értékkel térjen vissza.
  A `printf()` hívással egy `Halló mindenki!` szöveget írunk ki a szabványos kimenetre.

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

Példa 4-32. Az `<informaltable>` elem

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

Példa 4-33. A `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

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

A `<screen>` elem

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

A `<prompt>` elem, `&prompt.root;` és `&prompt.user;` egyedek

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

  > Megjegyzés: A `&prompt.root;` és `&prompt.user;` egyedek nem részei az eredeti DocBook DTD-nek, csupán a FreeBSD kiterjesztései.

A `<userinput>` elem

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

Példa 4-34. A `<screen>`, `<prompt>` és `<userinput>` elemek

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

> Megjegyzés: 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.

## 4.2.5. Belső elemek

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

Példa 4-35. Az `<emphasis>` elem

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

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

Példa 4-36. Idézetek

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.

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

Példa 4-37. Billentyűk, egérgombok és azok kombinációja

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+jobb egyérgomb segítségével tudjuk mozgatni az ablakokat.

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

Példa 4-38. Alkalmazások, parancsok és kapcsolók

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.

> Megjegyzés: Figyeljük meg, hogy a `&man.`parancs`.`szekció`;` jelölés mennyivel könnyebben olvasható.

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

Példa 4-39. A `<filename>` elem

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

### 4.2.5.6. A portok nevei

> A FreeBSD kiterjesztése: 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.

Példa 4-40. A `<filename>` elem és a `package` role együttes használata

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

### 4.2.5.7. Eszközök

> A FreeBSD kiterjesztése: 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.

Példa 4-41. A `<devicename>` elem

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

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

> A FreeBSD kiterjesztése: 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.

Nem szerepel a `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.

Példa 4-42. A `<hostid>` elem és a különböző role értékek

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

### 4.2.5.9. Felhasználói nevek

> A FreeBSD kiterjesztése: 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.

Példa 4-43. A `<username>` elem

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

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

> A FreeBSD kiterjesztése: 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.

Példa 4-44. A `<maketarget>` és a `<makevar>` elemek

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

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

Példa 4-45. A `<literal>` elem

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

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

Példa 4-46. A `<replaceable>` elem

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

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

Példa 4-47. Az `<errorname>` elem

A használat módja:

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

Így jelenik meg:

    “Panic: cannot mount root”

## 4.2.6. Képek

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

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

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

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

  Helyezzünk el egy `<imagedata>` elemet az `<imageobject>` elembe. A `fileref` tulajdonságban kell megadnunk kiterjesztés nélkül a képhez tartozó állomány nevét. A stíluslapok maguktól megállapítják a neki megfelelő kiterjesztést.
  Az első `<textobject>` elemben szerepelnie kell egy `<literallayout>` elemnek, ahol a `class` tulajdonság értéke `monospaced` legyen. Itt tudjuk megmutatni milyen jól tudunk ASCII karakterekkel rajzolni. Ezt a dokumentum nyers szöveges változatának előállításakor fogjuk felhasználni.

  A `<literallayout>` elem belsejének első és utolsó sorában megfigyelhetjük, hogy közvetlenül a szöveges ábra mellett kezdődnek, így garantálhatjuk, hogy semmilyen további felesleges szóköz nem jelenik meg a generált változatban.

  A második `<textobject>` elemben egy `<phrase>` elemnek kell lennie. Ennek tartalma lesz a HTML változatban a képhez tartozó `alt` tulajdonság értéke.

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

  A könyvtár nevét is meg kell adnunk a `fileref` tulajdonságban.

Az ennek megfelelő `Makefile` állomány tartalma:

    …
    IMAGES=  fejezet1/fejezet1.png
    …

Ezzel már minden remekül működik.

## 4.2.7. Hivatkozások

> Megjegyzés: A hivatkozások is belső elemek.

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

Példa 4-48. Az `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.

Példa 4-49. Az `<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.

Példa 4-50. Az `<xref>` elem

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

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

Példa 4-51. A `<link>` elem

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

> Megjegyzés: 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.

> Megjegyzés: A `<link>` elemmel már tudunk hivatkozni `<anchor>` elemek `id` tulajdonságaira, hiszen a `<link>` elemben már megadható a hivatkozás szövege.

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

Példa 4-52. Az `<ulink>` elem

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

### Megjegyzések

[1] | Ennek rövid története a http://www.oasis-open.org/docbook/intro.shtml#d0e41 címen olvasható.
[2] | A felsorolások megadására a DocBook további lehetőségeket is felkínál, azonban ezekkel itt most nem foglalkozunk.

Előző | Tartalom | Következő
Az SGML alkalmazása | Fel | * Stíluslapok

Ha kérdése van a FreeBSD-vel kapcsolatban, a következő címre írhat (angolul): <freebsd-questions@FreeBSD.org>.
Ha ezzel a dokumentummal kapcsolatban van kérdése, kérjük erre a címre írjon: <gabor@FreeBSD.org>.