doc/hu_HU.ISO8859-2/books/fdp-primer/structure/chapter.xml

<?xml version="1.0" encoding="iso-8859-2"?>
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.

     Redistribution and use in source (SGML DocBook) and 'compiled' forms
     (SGML HTML, PDF, PostScript, RTF and so forth) with or without
     modification, are permitted provided that the following conditions
     are met:

      1. Redistributions of source code (SGML DocBook) must retain the above
         copyright notice, this list of conditions and the following
         disclaimer as the first lines of this file unmodified.

      2. Redistributions in compiled form (transformed to other DTDs,
         converted to PDF, PostScript, RTF and other formats) must reproduce
         the above copyright notice, this list of conditions and the
         following disclaimer in the documentation and/or other materials
         provided with the distribution.

     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
     POSSIBILITY OF SUCH DAMAGE.

     $FreeBSD$
-->

<!-- The FreeBSD Hungarian Documentation Project
     Translated by: PALI, Gabor <pgj@FreeBSD.org>
     %SOURCE%  en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml
     %SRCID%   1.19
-->

<chapter id="structure" lang="hu">
  <title>A dokumentumok szervezése a <filename>doc/</filename>
    könyvtáron belül</title>

  <para>A <filename>doc/</filename> könyvtár tartalma egy
    adott módon szervezõdik, és ennek megfelelõen
    a &os; Dokumentációs Projektben
    készített dokumentumok is adott módon
    kerülnek elrendezésre.  Célunk ezzel
    megkönnyíteni az újabb
    dokumentációk felvételét,
    illetve:</para>

  <orderedlist>
    <listitem>
      <para>leegyszerûsíteni az új dokumentum
	automatikus átalakítását
	különbözõ formátumokba;</para>
    </listitem>

    <listitem>
      <para>megteremteni a különbözõ dokumentumok
	közti következetes elrendezést, így
	könnyebben lehet köztük váltani munka
	közben;</para>
    </listitem>

    <listitem>
      <para>segíteni az új dokumentumok helyének
	egyszerû eldöntésében.</para>
    </listitem>
  </orderedlist>

  <para>Mindezek mellett a dokumentációt
    tároló könyvtárnak olyan
    felépítésûnek kell lennie, amely
    lehetõvé teszi több különbözõ
    nyelven és több különbözõ
    kódolásban írt dokumentumok kényelmes
    elhelyezését.  Fontos hozzátennünk, hogy a
    könyvtár szerkezete nem követel meg semmilyen
    különleges elõfeltételezést vagy
    kulturális berendezkedést.</para>

  <sect1 id="structure-top">
    <title>A legfelsõ szint: a <filename>doc/</filename>
      könyvtár</title>

    <para>A <filename>doc/</filename> további két,
      különleges névvel és jelentéssel
      rendelkezõ könyvtárat rejt.</para>

    <segmentedlist>
      <segtitle>Könyvtár</segtitle>

      <segtitle>Leírás</segtitle>

      <seglistitem>
	<seg><filename>share/</filename></seg>

	<seg>Ebben a könyvtárban találjuk azokat az
	  állományokat, amelyek függetlenek az egyes
	  fordításoktól és
	  kódolásoktól.  A benne
	  található alkönyvtárakon
	  keresztül tovább csoportosítódik a
	  tartalmuk.  Például a dokumentáció
	  elõállításához
	  kapcsolódó &man.make.1; infrastruktúra
	  állományai a <filename>share/mk</filename>,
	  miközben a SGML használatához
	  szükséges további állományok
	  (mint például a &os; kiterjesztéseit
	  tartalmazó DocBook DTD) a
	  <filename>share/xml</filename> alkönyvtárban
	  helyezkednek el.</seg>
      </seglistitem>

      <seglistitem>
	<seg><filename><replaceable>nyelv</replaceable>.<replaceable>kódolás</replaceable>/</filename></seg>

	<seg>Minden fordításhoz és annak
	  kódolásához tartozik egy
	  könyvtár, például
	  <filename>en_US.ISO8859-1</filename> vagy
	  <filename>hu_HU.ISO8859-2</filename>.  A nevek alapvetõen
	  hosszúak, de pontosan meghatározzák az
	  adott nyelvet és a dokumentáció
	  írásához alkalmazott
	  kódolást.  Ezzel igyekszük
	  felkészülni olyan esetekre, amikor a
	  fordítócsapatok egy nyelven többféle
	  kódolás szerint is szeretnének
	  dokumentációt készíteni.  Ez a
	  megoldás egyben kiutat szolgáltat egy esetleges
	  késõbbi, Unicode kódolásra
	  váltás során felmerülõ
	  problémák elõl.</seg>
      </seglistitem>
    </segmentedlist>
  </sect1>

  <sect1 id="structure-locale">
    <title>A
      <filename><replaceable>nyelv</replaceable>.<replaceable>kódolás</replaceable>/</filename>
      könyvtárak</title>

    <para>Ezek a könyvtárak tartalmazzák magukat a
      dokumentumokat.  A dokumentumokat ezen a szinten a
      különbözõ könyvtárak neveinek
      megfelelõen három vagy több
      kategóriára osztjuk.</para>

    <segmentedlist>
      <segtitle>Könyvtár</segtitle>

      <segtitle>Tartalom</segtitle>

      <seglistitem>
	<seg><filename>articles</filename></seg>

	<seg>Az itt található dokumentumokat a DocBook
	  <sgmltag>article</sgmltag> eleme szerint (vagy egy azzal
	  egyenlõ megoldással) jelöltük.
	  Viszonylag rövid, szakaszokra osztott dokumentumokat
	  találhatunk itt.  Általában egyetlen HTML
	  állományként érhetõek
	  el.</seg>
      </seglistitem>

      <seglistitem>
	<seg><filename>books</filename></seg>

	<seg>Ebben a könyvtárban a DocBook
	  <sgmltag>book</sgmltag> eleme szerint (vagy egy azzal
	  egyenlõ megoldással) jelöltük.
	  Hosszabb, fejezetekre osztott dokumentum.
	  Általában egyetlen nagyobb HTML
	  állományként (a gyors
	  internetkapcsolattal rendelkezõ, vagy a dokumentumot a
	  böngészõbõl nyomtatni
	  kívánó egyének
	  számára), illetve több kisebb
	  állományként együtteseként is
	  elérhetõ.</seg>
      </seglistitem>

      <seglistitem>
	<seg><filename>man</filename></seg>

	<seg>A rendszerhez tartozó man oldalak
	  fordításai.  A lefordított szakaszoknak
	  megfelelõen ebben a könyvtárban egy vagy
	  több <filename>man<replaceable>n</replaceable></filename>
	  nevû alkönyvtárat találhatunk.</seg>
      </seglistitem>
    </segmentedlist>

    <para>Nem mindegyik
      <filename><replaceable>nyelv</replaceable>.<replaceable>kódolás</replaceable></filename>
      könyvtár tartalmazza ezeket az
      alkönyvtárakat.  Az egyes fordítások
      tartalma mindig attól függ, hogy az adott
      fordítócsapatnak mennyit sikerült eddig
      lefordítania.</para>
  </sect1>

  <sect1 id="structure-document">
    <title>Az egyes dokumentumokkal kapcsolatos
      tudnivalók</title>

    <para>Ebben a szakaszban a &os; Dokumentációs Projekt
      keretein belül gondozott különbözõ
      dokumentumokat ismerhetjük meg részletesebben.</para>

    <sect2>
      <title>A kézikönyv</title>

      <subtitle><filename>books/handbook/</filename></subtitle>

      <para>A kézikönyv a &os; kiterjesztéseit
	tartalmazó DocBook DTD szerint készült.</para>

      <para>A kézikönyv a DocBook <sgmltag>book</sgmltag>
	elemének megfelelõen szervezõdik.  Több
	<sgmltag>part</sgmltag> elemmel jelölt részbõl
	áll, amelyek mindegyike több
	<sgmltag>chapter</sgmltag> elemmel jelölt fejezetet foglal
	magában.  Ezek a fejezetek további szakaszokra
	(<sgmltag>sect1</sgmltag>) bomlanak, amelyek helyenként
	alszakaszokra (<sgmltag>sect2</sgmltag>,
	<sgmltag>sect3</sgmltag>) oszlanak, és így
	tovább.</para>

      <sect3>
	<title>Fizikai szervezés</title>

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

	<note>
	  <para>A kézikönyv szervezése
	    idõrõl-idõre változik, ezért
	    könnyen elõfordulhat, hogy ez a dokumentum csak
	    kissé késve követi ezeket a
	    változtatásokat.  Ha további
	    kérdéseink lennének a
	    kézikönyv szervezésérõl,
	    bátran írjunk a &a.doc;
	    címére!</para>
	</note>

	<sect4>
	  <title><filename>Makefile</filename></title>

	  <para>A <filename>Makefile</filename>
	    állományban definiálódnak olyan
	    változók, amelyek a SGML források
	    különbözõ formátumúra
	    alakításának menetét
	    befolyásolják, illetve hivatkozik a
	    kézikönyv forrásaira.  Ezután
	    beemeli a <filename>doc.project.mk</filename>
	    állományt, és így
	    lényegében betölti a dokumentumok
	    átalakításáért
	    felelõs további
	    utasításokat.</para>
	</sect4>

	<sect4>
	  <title><filename>book.xml</filename></title>

	  <para>Ez a kézikönyv legfelsõ szintû
	    dokumentuma.  Ebben van a kézikönyv <link
	      linkend="sgml-primer-doctype-declaration">dokumentípus-deklarációja</link>,
	    illetve a szerkezetét leíró
	    további elemek.</para>

	  <para>A <filename>book.xml</filename> az
	    <filename>.ent</filename> kiterjesztésû
	    állományokat <link
	      linkend="sgml-primer-parameter-entities">paraméteregyedek</link>
	    segítségével tölti be.  Ezek az
	    állományok (amelyekrõl késõbb
	    még szó lesz) aztán a
	    kézikönyv további részeiben
	    használt <link
	      linkend="sgml-primer-general-entities">általános
	      egyedeket</link> definiálnak.</para>
	</sect4>

	<sect4>
	  <title><filename><replaceable>könyvtár</replaceable>/chapter.xml</filename></title>

	  <para>A kézikönyv egyes fejezetei
	    egymástól különálló
	    könyvtárakban, <filename>chapter.xml</filename>
	    nevû állományokban
	    tárolódnak.  Ezeket a könyvtárakat
	    az adott fejezetet jelölõ
	    <sgmltag>chapter</sgmltag> <literal>id</literal>
	    tulajdonsága szerint szokták elnevezni.</para>

	  <para>Például ha az egyik fejezet
	    forrásában a következõ sor
	    olvasható:</para>

	  <programlisting><![CDATA[
<chapter id="kernelconfig">
...
</chapter>]]></programlisting>

	  <para>Ekkor a <filename>chapter.xml</filename> nevû
	    állományt tartalmazó könyvtár
	    neve <filename>kernelconfig</filename> lesz.  Egy ilyen
	    állomány általában a teljes
	    fejezetet tartalmazza.</para>

	  <para>A kézikönyv HTML változatának
	    készítése során ebbõl a
	    <filename>kernelconfig.html</filename>
	    állomány fog keletkezni.  Ezt azonban az
	    <literal>id</literal> értéke határozza
	    meg, semmi köze nincs a könyvtár
	    elnevezéséhez.</para>

	  <para>A kézikönyv korábbi
	    változataiban az összes forrás a
	    <filename>book.xml</filename> állománnyal
	    volt egy szinten, és az adott
	    <sgmltag>chapter</sgmltag> elemek <literal>id</literal>
	    tulajdonságának megfelelõen került
	    elnevezésre.  Az egyes fejezetekhez most már
	    külön-külön tudunk képeket
	    csatolni, amelyeket a fejezeteknek megfelelõ
	    könyvtárban kell elhelyezni a <filename
	      class="directory">share/images/books/handbook</filename>
	    könyvtáron belül.  Ha honosítani
	    akarjuk a képeket, akkor viszont ügyeljünk
	    arra, hogy az adott fejezet könyvtárába,
	    az SGML források mellé tegyük a
	    lefordított képeket.  A
	    névütközés egy idõ után
	    úgyis elkerülhetetlenné válik,
	    és sok, kevés állományt
	    tartalmazó könyvtárral
	    egyébként is könnyebb dolgozni, mint egy
	    sok állományt tartalmazó
	    könyvtárral.</para>

	  <para>A kézikönyv forrásaiban könnyen
	    láthatjuk, hogy sok ilyen könyvtár van,
	    bennük egy-egy <filename>chapter.xml</filename>
	    állománnyal.  Például
	    <filename>basics/chapter.xml</filename>,
	    <filename>introduction/chapter.xml</filename> és
	    <filename>printing/chapter.xml</filename>.</para>

	  <important>
	    <para>A fejezeteket és könyvtárakat nem
	      szabad semmilyen sorrendiségre utaló
	      módon elnevezni.  A fejezetek elrendezése
	      ugyanis változhat a kézikönyv egy
	      esetleges átszervezése során.  Az
	      ilyen átszervezések során pedig
	      (általában) nem lenne szabad
	      állományokat átnevezni (hacsak
	      komplett fejezeteket nem mozgatunk fentebb vagy lentebb a
	      szerkezetben).</para>
	  </important>

	  <para>Az egyes <filename>chapter.xml</filename>
	    állományok önmagukban teljes SGML
	    dokumentumok.  Különösen azért, mert
	    semmilyen <literal>DOCTYPE</literal> sor nem
	    található az elejükön.</para>

	  <para>Ez abból a szempontból
	    hátrányos, hogy ezeket az
	    állományokat ezért nem tudjuk
	    normál SGML állományokként
	    kezelni.  Emiatt ezeket nem lehet egyszerûen, a
	    kézikönyvhöz hasonlóan módon
	    HTML, RTF, PS vagy más egyéb formátumba
	    átalakítani.  Ezért tehát
	    könnyen elõfordulhat, hogy a fejezetek
	    megváltoztatásakor a
	    <emphasis>teljes</emphasis> kézikönyvet elõ
	    kell állítanunk.</para>
	</sect4>
      </sect3>
    </sect2>
  </sect1>
</chapter>