3.3.1.1. Katalógusok

Az SGML feldolgozónak a dokumentum feldolgozása során valamilyen módon az így megadott formális publikus azonosítóból vissza kell tudnia fejtenie a DTD-t tartalmazó állomány nevét.

Mindehhez egy katalógusra lesz szükségünk. Ezek (amelyeket általában catalog néven találhatunk meg) tartalmazzák az azonosítók és a hozzájuk tartozó állománynevek összerendeléseit. Például, ha egy katalógusban a következő sor található:

PUBLIC "-//W3C//DTD HTML 4.0//EN"             "4.0/strict.dtd"

Az SGML feldolgozó a catalog állományt tartalmazó könyvtár 4.0 alkönyvtárában levő strict.dtd állományban fogja keresni az adott DTD-t.

Nézzünk szét kicsit a /usr/local/share/xml/html/catalog állományban. Ez tartalmazza a textproc/docproj portból telepített HTML DTD-kre vonatkozó állományinformációkat.

3.3.1.2. Az SGML_CATALOG_FILES környezeti változó

Az SGML feldolgozónak valahogy tudnia kell hol keresse a katalógusokat. Számos implementációjuk parancssori paramétereken keresztül teszi lehetővé a feldolgozás során használni kívánt katalógus vagy katalógusok felsorolását.

Emellett az SGML_CATALOG_FILES környezeti változó segítségével is megadhatóak ezek az állományok. A változó értékének a (teljes elérési útvonallal kifejtett) katalógusok vesszővel tagolt felsorolását kell beállítani.

Az esetek döntő többségében a következő állományokat kell ilyen módon felvennünk:

• /usr/local/share/xml/docbook/4.1/catalog

• /usr/local/share/xml/html/catalog

• /usr/local/share/xml/iso8879/catalog

• /usr/local/share/xml/jade/catalog

Ezt egyébként korábban már elvégeztük.

3.7.3.1. Állományok beillesztése általános egyedek segítségével

3.7.3.2. Állományok beillesztése paraméteregyedek segítségével

3.8.1.1. CDATA, RCDATA

A kulcsszavakkal a jelölt szakasz tartalmi modelljét tudjuk megváltoztatni.

Az SGML elemző a dokumentum feldolgozása során tárol egy ún. “tartalmi modellt”.

Röviden úgy foglalhatnánk össze, hogy ez a tartalmi modell írja le az elemző részéről várt információkat és azok feldolgozását.

A két ilyen leghasznosabb tartalmi modell a CDATA és az RCDATA.

A CDATA jelentése “Character Data”, vagyis “karakteres adat”. Az elemző ebben a tartalmi modellben kizárólag csak karaktereket lát. Ebben a modellben a < és & szimbólumok elveszítik különleges jelentésüket.

Az RCDATA jelentése “Entity references and character data”, vagyis “egyedhivatkozások és karakteres adatok”. Ebben a tartalmi modellben az elemző karakterekre és egyedekre számít. A < szimbólum ilyenkor elveszíti a különleges jelentését, azonban az & továbbra is általános egyedek kezdetét fogja jelölni.

Ezek használata különösen hasznos abban az esetben, amikor rengeteg < és & karaktert tartalmazó nyers szöveget akarunk beilleszteni valahova a dokumentumba. Természetesen ez megoldható úgy is, ha minden < szimbólumot &lt; karaktersorozattá, illetve minden & szimbólumot &amp; karaktersorozattá alakítunk, de sokkal könnyebb ezeket a szakaszokat CDATA típusúnak megjelölni. Az SGML elemzők ilyenkor tehát figyelmen kívül hagyják a tartalomban talált < és & szimbólumokat.

<para>Ebben a példában láthatjuk hogyan tudunk sok <literal>&lt;</literal>
  és <literal>&amp;</literal> szimbólumot tartalmazó szöveget elhelyezni
  a dokumentumunkban.  A minta most egy HTML kódrészlet lesz, az ezt övező
  szöveg (<para>) és (<programlisting>) pedig DocBook.</para>

<programlisting>
  <![CDATA[  
    <p>Ezzel a példával mutatjuk HTML elemek használatát a
      dokumentumban.  Mivel elég sok relációjelet kell ilyenkor megadni,
      sokkal egyszerűbb azt mondani, hogy legyen az egész példa egy
      CDATA szakaszban, mintsem végig egyedekkel jelöljük a balra és
      jobb nyitó relációjeleket.</p>

    <ul>
      <li>Ez egy listaelem</li>
      <li>Ez egy másik listaelem</li>
      <li>Ez már egy harmadik listaelem</li>
    </ul>

    <p>Itt a vége a példának.</p>
  ]]>
</programlisting>

3.8.1.2. INCLUDE és IGNORE

Az INCLUDE kulcsszó megadásakor a jelölt szakasz teljes tartalma feldolgozódik. Ezzel szemben viszont az IGNORE kulcsszó esetén a jelölt szakasz tartalmát figyelmen kívül fogja hagyni az elemző és ezáltal nem dolgozódik fel, tehát nem jelenik meg az eredményben.

<![ INCLUDE [
  Ez a szöveg feldolgozódik és beillesztődik.
]]>

<![ IGNORE [
  Ez a szöveg nem dolgozódik fel és nem is illesztődik be.
]]>

Ezek önmagukban nem túlzottan hasznosak, elvégre, ha el akarunk távolítani egy szövegrészt a dokumentumunkból, akkor vagy egyszerűen kivágjuk, vagy megjegyzésbe tesszük.

Sokkal hasznosabbá válhatnak viszont a számunkra, ha észrevesszük, hogy paraméteregyedek segítségével mindez vezérelhető. Emlékezzünk vissza, hogy a paraméteregyedek csak SGML környezetben használhatóak, és a jelölt szakaszokhoz tartozó kulcsszavak pontosan egy ilyen SGML környezetben vannak.

Például tegyük fel, hogy egy dokumentáció nyomtatott és elektronikus változatán dolgozunk egyszerre. Az elektronikus változatban szeretnénk azonban néhány olyan elemet is betenni, amelyeket nem akarunk megjelentetni nyomtatásban.

Hozzunk létre egy paraméteregyedet és legyen az értéke INCLUDE. Készítsük el a dokumentumot, és jelölt szakaszokkal határoljuk el a csak az elektronikus változat megjelenő részeket. Ezekben a jelölt szakaszokban a kulcsszavak helyére írjuk be az előbbi paraméteregyedet.

Amikor a dokumentumot nyomtatásra akarjuk előkészíteni, akkor legyen a paraméteregyed értéke IGNORE, majd dolgozzuk fel újra az egész dokumentumot.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % elektronikus.valtozat "INCLUDE">
]]>

...

<![ %elektronikus.valtozat [
  Ez a rész csak a dokumentum elektronikus változatában fog megjelenni.
]]>

<!ENTITY % elektronikus.valtozat "IGNORE">

4.1.3.1. Fejlécek

A HTML lehetővé teszi fejlécek jelölését egészen hat különböző szintig.

A legnagyobb és legkiemelkedőbb fejléc a <h1>, majd ezt követi a <h2>, egészen a <h6> címkéig.

Az elem tartalma a fejléc szövege lesz.

<h1>Első szakasz</h1>

<!-- Ide kerül a dokumentum bevezető része -->

<h2>Ez az első szakasz fejléce</h2>

<!-- Az első szakasz tartalma következik -->

<h3>Ez az első alszakasz fejléce</h3>

<!-- Az első alszakasz tartalma itt foglal helyet -->

<h2>Ez a második szakasz fejléce</h2>

<!-- A második szakasz tartalma ezen a részen lesz -->

A HTML oldalaknak általában rendelkezniük kell első szintű fejléccel (<h1>). Ez tetszőleges számú második szintű fejlécet (<h2>) tartalmazhat, amelyek szintén tetszőleges mennyiségű harmadik szintű fejlécet. Ügyeljünk arra, hogy minden <hn> elem mindig a nála eggyel nagyobb szintű elemet tartalmazza, a sorszámozásban tehát nem javasolt közöket hagyni.

<h1>Első szakasz</h1>

<!-- A dokumentum bevezetője -->

<h3>Alszakasz</h3>

<!-- Nem jó, mert kimaradt a <h2> szint! -->

4.1.3.2. Bekezdések

A HTML egyetlen bekezdésfajtát ismer, ez a <p>.

<p>Ez egy bekezdés.  Szinte bármilyen más elemet tartalmazhat.</p>

4.1.3.3. Idézetblokkok

Az idézetblokkok más dokumentumok nagyobb részeinek idézésére használhatóak az aktuális bekezdésen túl.

<p>Részlet a Szózatból:</p>

<blockquote>Hazádnak rendületlenűl
  Légy híve, oh magyar,
  Bölcsőd az 's majdan sírod is,
  Melly ápol 's eltakar.

  A' nagy világon e' kivűl
  Nincsen számodra hely,
  Áldjon vagy verjen sors' keze,
  Itt élned, halnod kell.

  Ez a' föld, mellyen annyiszor
  Apáid' vére folyt;
  Ez, mellyhez minden szent nevet
  Egy ezredév csatolt.

  Itt küzdtenek honért a' hős
  Árpádnak hadai,
  Itt törtek össze rabigát
  Hunyadnak karjai.

  Szabadság! Itten hordozák
  Véres zászlóidat,
  'S elhulltanak legjobbjaink
  A' hosszu harcz alatt.</blockquote>

4.1.3.4. Felsorolások

A dokumentumokban háromféle felsorolást használhatunk: sorszámozott, sorszámozás nélkül és definíciós.

Röviden úgy mutathatnánk be ezeket a formátumokat, hogy a sorszámozott felsorolásban az elemek elé számok kerülnek, a sorszámozás nélküli esetben pontok, a definíciós felsorolásban pedig a bejegyzések két részéből jönnek létre az elemek. Ezek közül az első részben a meghatározandó fogalom található, míg a második részben annak meghatározása.

A sorszámozott felsorolásokat az <ol> elem jelzi, a sorszámozás nélküli felsorolásokat az <ul> elem, végül a definíciós felsorolásokat a <dl> elem.

A sorszámozott és sorszámozás nélküli felsorolások a felsorolás elemeit tartalmazzák, amelyeket a <li> elemekkel vezetünk be. A felsorolások elemeinek szöveges tartalma lehet, vagy ha ezeket becsomagoljuk egy vagy több <p> elembe, további elemeket tartalmazhatnak.

A definíciós felsorolások meghatározandó fogalmakat (<dt>) és meghatározásokat (<dd>) tartalmazhatnak. A meghatározandó fogalmat tartalmazó részben csak belső elemek szerepelhetnek. A meghatározásokban viszont további blokkok is megjelenhetnek.

<p>Egy sorszámozás nélkül felsorolás.  A felsorolás elemei előtt minden
  bizonnyal pontok fognak megjelenni.</p>

<ul>
  <li>Első elem</li>

  <li>Második elem</li>

  <li>Harmadik elem</li>
</ul>

<p>Egy sorszámozott lista, ahol az elemek több bekezdésből állnak.
  Mindegyik elem (figyelem: nem mindegyik bekezdés) előtt egy sorszámnak kell
  szerepelnie.</p>

<ol>
  <li>
    <p>Ez az első elem.  Ennek csak egy bekezdése van.</p>
  </li>

  <li>
    <p>Ez a második elem első bekezdése.</p>

    <p>Ez a második elem második bekezdése.</p>
  </li>

  <li>
    <p>Ez az első és egyetlen bekezdés a harmadik elemben.</p>
  </li>
</ol>

<dl>
  <dt>Első fogalom</dt>

  <dd>
    <p>Az első fogalom meghatározásának első bekezdése.</p>

    <p>Az első fogalom meghatározásának második bekezdése.</p>
  </dd>

  <dt>Második fogalom</dt>

  <dd>
    <p>A második fogalom meghatározásának első bekezdése.</p>
  </dd>

  <dt>Harmadik fogalom</dt>

  <dd>
    <p>A harmadik fogalom meghatározásának első bekezdése.</p>
  </dd>
</dl>

4.1.3.5. Formázott szöveg

Megadhatjuk, hogy a szöveg egyes részei pontosan abban a formában kerüljenek a felhasználó elé, ahogy az eredetileg szerepel. Ilyenkor általában a szöveg rögzített szélességű betűtípussal jelenik meg, az egymás mellett levő szóközök nem vonódnak össze, a sortörések hatása fontossá válik.

Mindezt a <pre> elemen keresztül érhetjük el.

<pre>  From: Gabor PALI &lt;[email protected]&gt;
  To: [email protected]
  Subject: Uj FreeBSD-cikk forditas: Naplozo UFS hasznalata asztali szamitogepeken

  Kedves listatagok!


    Nemreg elkeszitettem az ``Implementing UFS Journaling on a Desktop
  PC'' neven szerepelo [1] FreeBSD-cikk magyar forditasat [2].
  Szeretnek megkerni mindenkit, akit erdekel a honositott valtozat,
  hogy olvassa el, nezze at, betatesztelje es mondjon rola velemenyt.
  Egyelore meg csak a sajat Perforce repositorynkbol erheto el, de a
  megadott linken naponta egyszer automatikusan frissul a HTML valtozat
  a feltoltott valtoztatasok (peldaul hibajavitasok) fuggvenyeben.
  Elore is nagyon szepen koszonom mindenkinek a segitseget!

  :g

  [1] http://www.freebsd.org/doc/en/articles/gjournal-desktop/
  [2] http://people.freebsd.org/~pgj/gjournal-desktop_hu/</pre>

4.1.3.6. Táblázatok

A táblázatos formában megjeleníteni kívánt információt jelöljük a <table> elemmel. A táblázatok egy több sorból (<tr> mint “table row”) állnak, amelyek egy vagy több adatcellát (<td> mint “table data”) tartalmaznak. Mindegyik cella tartalmazhat további blokkokat, például bekezdéseket vagy listákat, de akár táblázatokat (ez a beágyazás tetszőleges mélységig folytatható). Ha a cella tartalma csak egyetlen bekezdés, akkor nincs szükség a <p> elem használatára.

<p>Ez egy 2x2-es táblázat.</p>

<table>
  <tr>
    <td>Bal felső cella</td>

    <td>Jobb felső cella</td>
  </tr>

  <tr>
    <td>Bal alsó cella</td>

    <td>Jobb alsó cella</td>
  </tr>
</table>

Egy cella több sorra vagy oszlopra is átnyúlhat. Ennek jelzéséhez a kiterjesztendő sorokhoz a rowspan és/vagy oszlopokhoz a colspan tulajdonságot adjuk meg a megfelelő értékkel.

<p>Egy magas keskeny cella a bal oldalon, mellette jobbra
  két rövid cella.</p>

<table>
  <tr>
    <td rowspan="2">Hosszú és keskeny</td>
  </tr>

  <tr>
    <td>Felső cella</td>

    <td>Alsó cella</td>
  </tr>
</table>

<p>Felül egy hosszú cella, alatt két rövidebb cella.</p>

<table>
  <tr>
    <td colspan="2">Felső cella</td>
  </tr>

  <tr>
    <td>Bal alsó cella</td>

    <td>Jobb alsó cella</td>
  </tr>
</table>

<p>Egy 3x3-as rácson a bal felső blokk 2x2 egymásba olvasztott
  cellából áll.  A többi cella normális.</p>

<table>
  <tr>
    <td colspan="2" rowspan="2">Bal felső nagy cella</td>

    <td>Jobb felső cella</td>
  </tr>

  <tr>
    <!-- Mivel a bal oldalon levő nagy cella beleolvad az első sorba,
         az első <td> a jobb oldalán jelenik meg -->

    <td>Jobb középső cella</td>
  </tr>

  <tr>
    <td>Bal alsó cella</td>

    <td>Bal középső cella</td>

    <td>Jobb alsó cella</td>
  </tr>
</table>

4.1.4.1. Az információ kiemelése

A HTML esetén a kiemelésnek két szintje létezik, az <em> és a <strong>. Ezek közül az <em> jelenti a hagyományos kiemelést és a <strong> az erősebbet.

Az <em> elem tartalma általában dőlt betűvel jelenik meg, miközben a <strong> elem tartalma félkövéren. Ez a megállapítás azonban nem minden esetben igaz, ezért nem szabad semmi ilyesmit feltételeznünk a használatukkor.

<p><em>Ezt</em> a részt kiemeltük, miközben <strong>ezt</strong> részt
  erősebben kiemeltük.</p>

4.1.4.2. Félkövér és dőlt formázás

Mivel a HTML tartalmaz konkrétan a megjelenítésre vonatkozó jelölőket is, ezért külön jelezni tudjuk a forrásban, hogy a szöveg melyik részét szeretnénk félkövéren vagy dőlten látni. Ezeket a funkciókat a <b>, illetve az <i> elemekkel érhetjük el.

<p><b>Ez</b> félkövér, <i>ez</i> pedig dőlt.</p>

4.1.4.3. Írógépszerű formázás

Az írógépszerűen (rögzített szélességű karakterekkel) írt szövegek formázásához a <tt> (mint “teletype”) elemet használhatjuk.

<p>Ezt a dokumentumot eredetileg Páli Gábor fordította,
  és a következő címen érhető el: <tt>[email protected]</tt>.</p>

4.1.4.4. Méretezés

Előfordulhat, hogy szeretnénk növelni vagy csökkenteni a szöveg megjelenítéséhez használt betűtípus méretét. Erre alapvetően három lehetőség kínálkozik.

1. Ágyazzuk az átméterezendő szöveget <big> és <small> elemekbe. Ezeket a címkéket tetszőleges mélységig egymásba tudjuk ágyazni, tehát írható olyan, hogy <big><big>Ez már sokkal nagyobb!</big></big>.

2. Használjuk a <font> elemet, és a size tulajdonságát állítsuk a +1 vagy -1 értékre. Ez hatása szerint megegyezik a <big> és a <small> elemek használatával, azonban ez a típusú megoldás már elavult.

3. A <font> size tulajdonsága 1 és 7 között állítható. A betű alapértelmezett mérete 3. Ez a megközelítés már elavult.

<p>Ez a szöveg <small>valamivel kisebb</small>.  Ez a
  a szöveg viszont <big>valamivel nagyobb</big>.</p>

<p>Ez a szöveg <font size="-1">valamivel kisebb</font>.  Ez a
  szöveg viszont <font size="+1">valamivel nagyobb</font>.</p>

<p>Ez a szöveg <font size="2">valamivel kisebb</font>.  Ez a
  szöveg viszont <font size="4">valamivel nagyobb</font>.</p>

4.1.5.1. Hivatkozás más dokumentumokra a Világhálón

A Világhálón elhelyezkedő dokumentumokat úgy tudjuk hivatkozni, ha ismerjük a helyüket.

A hivatkozást az <a> elemmel adhatjuk meg, amelynek a href tulajdonsága tartalmazza a hivatkozott dokumentum helyét. Az elem tartalma ekkor egy hivatkozássá változik, és a felhasználó számára is jól látható módon jelenik meg (aláhúzással, más színnel, más egérmutatóval és így tovább).

<p>Erre vonatkozóan részletesebb információkat a
  <a href="http://www.FreeBSD.org/">FreeBSD honlapján</a> találhatunk.</p>

Ezeket a hivatkozások a felhasználót az adott dokumentum elejére irányítják.

4.1.5.2. A dokumentumok más részeinek hivatkozása

A dokumentumok egyéb részeire (akár ugyanazon a dokumentumon belül) csak akkor tudunk hivatkozni, ha a szerző előzetesen hivatkozási pontokat helyeztünk el bennük.

Hivatkozási pontokat szintén <a> elemekkel adhatunk meg, azonban a href tulajdonság helyett a name használatával.

<p><a name="bekezd1">Ez</a> a bekezdés a hivatkozásokban a <tt>bekezd1</tt>
  névvel érhető el.</p>

A dokumentum így megnevezett részét egy egyszerű hivatkozás készítésével tudjuk elérni, azonban a hivatkozási pont neve elé tennünk kell egy # jelet.

<p>A témáról további információkat az <tt>ize.html</tt>
  <a href="ize.html#bekezd1">első bekezdésében</a> találhatunk.</p>

Ha egy hivatkozási pontra ugyanazon a dokumentumon belül szeretnénk hivatkozni, akkor nyugodtan elhagyhatjuk a dokumentum nevét, elegendő egyszerűen magát a hivatkozási pontot megadnunk (természetesen a hozzá tartozó # jellel együtt).

<p>A témáról további információkat az
  <a href="#bekezd1">első bekezdésben</a> találhatunk.</p>

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

6.3.1.1. Fizikai szervezés

A kézikönyv forrásai több különböző állományban és könyvtárban a handbook könyvtáron belül találhatóak.

<chapter id="kernelconfig">
...
</chapter>

7.3.1.1. Változók

Ha nem állítjuk be a dokumentum Makefile állományában, akkor a DOCFORMAT és a MAINTAINER változók ezen a helyen kapnak értéket.

A PREFIX adja azt a könyvtárat, amelyen belül elérhetőek a dokumentáció előállításához szükséges eszközök. A csomagok és portok átlagos használata esetén ez a /usr/local.

A PRI_LANG adja meg azt a nyelvet és kódolást, amely a dokumentációt olvasó felhasználó számára elsődlegesként leginkább elfogadott. Alapértelmezés szerint ez az amerikai angol.

7.3.1.2. Elágazások

A .if defined(DOC) sorban a Makefile állományokban megadható elágazásokra láthatunk példát. Hasonlóan más programokhoz, a Makefile működését tudjuk meghatározni egy logikai kifejezés igazságértéktől függően. Ebben a kifejezésben a defined függvény, amely megadja, hogy a paramétereként megadott változó definiált-e.

A következő elágazásban, vagyis az .if ${DOCFORMAT} == "docbook" utasításban azt vizsgáljuk meg, hogy a DOCFORMAT változó értéke "docbook" vagy sem. Amennyiben a válasz erre igen (vagyis “igaz”), beemeljük a doc.docbook.mk tartalmát.

Az előbb említett két elágazást rendre az .endif kulcsszóval zárjuk le.

7.3.2.1. Változók

• A SUBDIR tartalmazza azokat az alkönyvtárakat, amelyeket a feldolgozás során be kell járnunk.

• A ROOT_SYMLINKS a dokumentáció főkönyvtárából szimbolikusan linkelendő könyvtárak neveit adja meg, amennyiben az adott nyelv (a PRI_LANG változó szerint) az elsődleges.

• A COMPAT_SYMLINK változót már korábban bemutattuk az alkönyvtári Makefile állományok című szakaszban.

7.3.2.2. Célok és makrók

A függőségi viszonyokat cél: függőség1 függőség2 ... formában írjuk fel, ahol így megmondjuk, hogy a cél létrehozásához először milyen elemeknek kell létezniük. Ezeket nevezzük függőségeknek.

A függőségi viszony megadása alatt lehetőségünk van részletezni a függőségekből a cél előállításához szükséges utasításokat. Ezt akkor kell megtenni, ha a cél és a függőségek közti átalakítást előzőleg még nem definiáltuk, vagy ha az adott esetben az átalakítás eltér a korábbiaktól.

A .USE nevű speciális függőség egy makróval egyenértékű eszköz használatára ad lehetőséget.

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

A fenti kódrészletben tehát a _SUBDIRUSE most már egy “makró” lesz, amely ha megjelenik a függőségek között, akkor a törzsében megadott parancsokat hajtja végre.

Mi különbözteti meg ezt a makrót a többi céltól? Két lényeges eltérés: először is, a benne megadott utasítások a rá függőségként hivatkozó célhoz társított átalakítást végző utasítások után fognak lefutni, másrészt nem befolyásolja a jelenleg feldolgozás alatt álló cél nevét tároló .TARGET változó értékét.

clean: _SUBDIRUSE
	rm -f ${CLEANFILES}

Ebben a kódrészletben a tehát clean esetében csak az rm -r ${CLEANFILES} parancs lefutása után fog végrehajtódni a _SUBDIRUSE makró tartalma. Ennek hatására a clean megy egyre lentebb és lentebb a könyvtárszerkezetben, miközben törli a előzőleg előállított állományokat.

7.3.2.3. Bővebben a feltételes kifejezésekről

• Az exists egy másik logikai függvény, amellyel lekérdezhetjük, hogy a paramétereként megadott állomány létezik-e.

• Az empty logikai függvény igaz értékű, ha a paramétereként megadott változó értéke üres.

• A target logikai függvény igaz értékű, ha a paraméterként megadott cél még nem létezik.

7.3.2.4. Ciklusszerverzési lehetőségek (.for)

A .for utasítás segítségével adott utasításokat tudunk elvégezni egy változó tartalmaként megadott, szóközökkel határolt elemekre. A ciklus belsejében egy változóból érhetjük el az aktuálisan feldolgozott elemet.

_SUBDIRUSE: .USE
.for entry in ${SUBDIR}
	@${ECHO} "===> ${DIRPRFX}${entry}"
	@(cd ${.CURDIR}/${entry} && \
	${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
.endfor

A fenti kódrészletben ha a SUBDIR üres, akkor nem történik semmi. Ha viszont egy vagy több elemet is tartalmaz, akkor a .for és az .endfor között megadott utasítások megismétlődnek minden egyes elem esetén. Ezek értékét a ciklus belsejében rendre a entry változóban veszi fel.

10.1.4.1. A címkék elrendezése

Az egy behúzási szinten található címkéket mindig válasszuk el egy üres sorral, a többi esetben viszont ne:

<article>
  <articleinfo>
    <title>NIS</title>

    <pubdate>1999 október</pubdate>

    <abstract>
      <para>...
	...
	...</para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>

  <sect1>
    <title>...</title>

    <para>...</para>
  </sect1>
</article>

10.1.4.2. A címkék tagolása

Bizonyos címkék, mint például az <itemizedlist>, amelyekben további címkék szerepelnek és nem karakteres adat, mindig egyedül állnak egy sorban.

A <para> és <term> címkék esetén viszont szükség van további címkékre a karakteres adatok befoglalásához, ezért ilyenkor a tartalom közvetlenül a címke után következik, ugyanabban a sorban.

Ugyanez érvényes az említett címketípusok zárásakor.

A címketípusok keveredése egy nyilvánvaló problémát eredményez.

Amikor egy karakteres adatot tárolni nem képes elemet nyitó címke közvetlenül követ egy karakteres adatokat bevezető címkét, külön sorba kell kerülniük. A második címkét a szabályok szerint kell behúzni.

Amikor egy karakteres adatokat befoglaló címke záródik közvetlenül a karakteres adatokat tartalmazni nem képes címke után, szerepelhetnek ugyanabban a sorban.