path: root/hu_HU.ISO8859-2/books/fdp-primer/doc-build/chapter.sgml

<?xml version="1.0" encoding="iso-8859-2"?>
<!-- Copyright (c) 1999 Neil Blakey-Milner, 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 THE AUTHOR "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/doc-build/chapter.sgml
     %SRCID%   1.16
-->

<chapter id="doc-build" lang="hu">
  <title>A dokumentáció
    elõállításának folyamata</title>

  <para>Ebben a fejezetben szeretnénk pontosan tisztázni
    <emphasis>hogyan szervezõdik a dokumentáció
    elõállításának folyamata</emphasis>
    és <emphasis>hogyan tudunk ebbe
    beavatkozni</emphasis>.</para>

  <para>A fejezet elolvasása során
    megismerjük:</para>

  <itemizedlist>
    <listitem>
      <para>az <link linkend="tools">SGML eszközeirõl
	szóló fejezetben</link> említetteken
	túl a &os; Dokumentációs Projekt keretein
	belül készített dokumentáció
	különbözõ változatainak
	elõállításához mire van
	még szükségünk;</para>
    </listitem>

    <listitem>
      <para>a dokumentumokhoz tartozó
	<filename>Makefile</filename> állományokban
	szereplõ <command>make</command>
	utasításokat, valamint a hivatkozott
	<filename>doc.project.mk</filename> vázlatos
	felépítését;</para>
    </listitem>

    <listitem>
      <para>további <command>make</command>
	változókon és célokon keresztül
	miként tudjuk testreszabni a dokumentáció
	különbözõ változatainak
	elõállítási folyamatát.</para>
    </listitem>
  </itemizedlist>

  <sect1 id="doc-build-toolset">
    <title>A &os; dokumentáció
      elõállításának
      eszközei</title>

    <para>Munkánk folyamán az itt felsorolt
      eszközök állnak rendelkezésünkre.
      Használjuk ki az általuk nyújtott
      lehetõségeket, amennyire csak tudjuk.</para>

    <itemizedlist>
      <listitem>
	<para>Az elsõdleges eszköz maga a
	  <command>make</command> parancs, pontosabban a
	  <application>Berkeley Make</application>.</para>
      </listitem>

      <listitem>
	<para>Csomagokat a &os; alaprendszerében
	  megtalálható <command>pkg_create</command>
	  programmal tudunk készíteni.  Ha nem &os; alatt
	  dolgozunk, akkor vagy csomagok nélkül kell
	  dolgoznunk, vagy magunknak kell ezeket
	  elkészítenünk.</para>
      </listitem>

      <listitem>
	<para>A <command>gzip</command>
	  segítségével lehet az
	  elõállított dokumentumok
	  tömörített változatát
	  elkészíteni.  Emellett még a
	  <command>bzip2</command> és <command>zip</command>
	  típusú tömörítés is
	  támogatott.  A <command>tar</command> programot is
	  támogatjuk, a csomagok
	  készítéséhez kell.</para>
      </listitem>

      <listitem>
	<para>A dokumentáció
	  telepítésének elfogadott eszköze az
	  <command>install</command> program.  Természetesen
	  léteznek egyéb megoldások is.</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>Nem valószínû, hogy ez az utolsó
	két eszközt ne lenne elérhetõ a
	rendszerünkön, csupán a teljesség
	kedvéért említettük meg ezeket.</para>
    </note>
  </sect1>

  <sect1 id="doc-build-makefiles">
    <title>A dokumentációt tároló
      könyvtárban található
      <filename>Makefile</filename> állományok</title>

    <para>A &os; Dokumentációs Projekt által
      használt könyvtárakban megtalálható
      <filename>Makefile</filename> állományoknak
      három típusa létezik:</para>

    <itemizedlist>
      <listitem>
	<para>Az <link linkend="sub-make">alkönyvtári
	  <filename>Makefile</filename> állományok</link>
	  egyszerûen csak továbbadják a parancsokat
	  az alkönyvtáraiknak.</para>
      </listitem>

      <listitem>
	<para>A <link linkend="doc-make">dokumentumokra vonatkozó
	  <filename>Makefile</filename> állományok</link>
	  írják le, hogy milyen dokumentumokat kellene az
	  adott könyvtárban
	  elõállítani.</para>
      </listitem>

      <listitem>
	<para>Az <link linkend="make-includes"><filename>.mk</filename>
	  állományok</link> segítik valamilyen
	  formában a dokumentumok
	  elõállítását.  Többnyire
	  <filename>doc.<replaceable>xxx</replaceable>.mk</filename>
	  névvel láthatóak.</para>
      </listitem>
    </itemizedlist>

    <sect2 id="sub-make">
      <title>Az alkönyvtári <filename>Makefile</filename>
	állományok</title>

      <para>Ezek a típusú <filename>Makefile</filename>
	állományok általában a
	következõ alakúak:</para>

      <programlisting>SUBDIR =articles
SUBDIR+=books

COMPAT_SYMLINK = en

DOC_PREFIX?= ${.CURDIR}/..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting>

      <para>Röviden összefoglalva: az elsõ négy
	nem üres sorban ún.  <command>make</command>
	változókat definiálunk.  Ezek rendre a
	<makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>
	és <makevar>DOC_PREFIX</makevar>.</para>

      <para>Az elsõ <makevar>SUBDIR</makevar> sornál,
	illetve a <makevar>COMPAT_SYMLINK</makevar> sorában
	láthatjuk hogyan kell egy új értéket
	beállítani egy ilyen
	változónak.</para>

      <para>A második <makevar>SUBDIR</makevar> sorban azt
	láthatjuk, hogyan tudunk a változó
	aktuális értékéhez
	továbbiakat hozzáfûzni.  Ebben az esetben
	tehát az utasítás
	végrehajtása után a
	<makevar>SUBDIR</makevar> értéke <literal>articles
	books</literal> lesz.</para>

      <para>A <makevar>DOC_PREFIX</makevar> esetében pedig olyan
	értékadást figyelhetünk meg, amelyik
	csak akkor hajtódik végre ténylegesen, ha a
	változónak addig még nem volt
	értéke.  Ez olyankor tud kapóra jönni,
	amikor a <makevar>DOC_PREFIX</makevar> nem pontosan az, amire a
	<filename>Makefile</filename> számít &mdash; a
	felhasználó ekkor meg tudja adni a helyes
	értéket.</para>

      <para>Ez így együttesen tehát mit is jelent?  A
	<makevar>SUBDIR</makevar> összefoglalja azokat a
	könyvtárakat, amelyekben a dokumentumok
	elõállításának
	folyamatának folytatódnia kell majd.</para>

      <para>A <makevar>COMPAT_SYMLINK</makevar> a kompatibilitás
	céljából létrehozott szimbolikus
	linkekre vonatkozik, amelyek (valamilyen csoda folytán)
	az adott nyelv hivatalos kódolására
	mutatnak (tehát például a
	<filename>doc/en</filename> a
	<filename>en_US.ISO8859-1</filename>
	könyvtárra).</para>

      <para>A <makevar>DOC_PREFIX</makevar> a &os;
	Dokumentációs Projekt
	fõkönyvtárához vezetõ utat adja
	meg.  Ezt nem mindig egyszerû megtalálni,
	ezért a rugalmasság kedvéért
	könnyedén felül is definiálható.
	A <makevar>.CURDIR</makevar> a <command>make</command> egyik
	saját belsõ változója, amelyben az
	aktuális könyvtár elérési
	útját tárolja.</para>

      <para>Végül az utolsó sorban a &os;
	Dokumentációs Projekt összes
	<filename>Makefile</filename> állományára
	vonatkozó, rendszerszintû
	<filename>doc.project.mk</filename> állományra
	hivatkozunk, amelyen keresztül az iménti
	változókból épül fel a
	dokumentumok elõállításának
	pontos menete.</para>
    </sect2>

    <sect2 id="doc-make">
      <title>A dokumentumokra vonatkozó
	<filename>Makefile</filename> állományok</title>

      <para>Ezekben a <filename>Makefile</filename>
	állományokban az adott könyvtárban
	található dokumentumok
	elõállítását
	leíró különbözõ
	<command>make</command> változók
	szerepelnek.</para>

      <para>Lássunk erre egy példát:</para>

      <programlisting>MAINTAINER=pgj@FreeBSD.org

DOC?= book

FORMATS?= html-split html

INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=

# Az SGML forrás
SRCS=  book.sgml

DOC_PREFIX?= ${.CURDIR}/../../..

.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting>

      <para>A <makevar>MAINTAINER</makevar> változó nagyon
	fontos.  A &os; Dokumentációs Projekten belül
	ezen a változón keresztül jelezhetjük a
	dokumentum birtoklását, vagyis
	karbantartási kötelezettségünket.</para>

      <para>A <makevar>DOC</makevar> hivatkozik (az
	<filename>.sgml</filename> kiterjesztés
	nélkül) az adott könyvtárban
	található dokumentum fõ
	forrására.  Emellett az <makevar>SRCS</makevar>
	változóban kell összefoglalnunk a
	dokumentumot alkotó források neveit.  Ebben
	érdemes megadni minden olyan állományt,
	amelynek megváltozása esetén újra
	elõ kell állítani az érintett
	dokumentumot.</para>

      <para>A <makevar>FORMATS</makevar>
	segítségével definiáljuk a dokumentum
	alapértelmezetten elõállítandó
	formátumait.  A <makevar>INSTALL_COMPRESSED</makevar>
	változóban a dokumentum
	elkészítésekor felhasználandó
	tömörítési formákat adhatjuk meg.
	A <makevar>INSTALL_ONLY_COMPRESSED</makevar>
	változó alapból üres, de ha adunk neki
	valamilyen egyéb értéket, akkor a
	dokumentumoknak csak a tömörített
	változata fog elkészülni.</para>

      <note>
	<para>A változók feltételes
	  értékadásáról már
	  volt szó <link linkend="sub-make">az elõzõ
	    szakaszban</link>.</para>
      </note>

      <para>A <makevar>DOC_PREFIX</makevar> változó
	és az <literal>.include</literal> utasítás a
	korábbiak alapján már ismerõs
	lehet.</para>
    </sect2>
  </sect1>

  <sect1 id="make-includes">
    <title>A &os; Dokumentációs Projekt
      <filename>.mk</filename> állományai</title>

    <para>Ezek az állományok legjobban talán
      önmagukon keresztül mutathatóak be.  A
      következõ rendszerszintû <filename>.mk</filename>
      állományokat használjuk a &os;
      Dokumentációs Projektben:</para>

    <itemizedlist>
      <listitem>
	<para>A <filename>doc.project.mk</filename> a központi
	  <filename>.mk</filename> állomány, amely
	  szükség szerint hivatkozik az összes
	  többi <filename>.mk</filename>
	  állományra.</para>
      </listitem>

      <listitem>
	<para>Az elõállítás és a
	  telepítés során a
	  <filename>doc.subdir.mk</filename> felelõs a dokumentumokat
	  tároló könyvtárak
	  bejárásért.</para>
      </listitem>

      <listitem>
	<para>A <filename>doc.install.mk</filename> tartalmazza a
	  karbantartóval és a telepítéssel
	  kapcsolatos változókat.</para>
      </listitem>

      <listitem>
	<para>A <filename>doc.docbook.mk</filename>
	  állomány csak akkor kerül
	  feldolgozásra, ha a <makevar>DOCFORMAT</makevar>
	  értéke <literal>docbook</literal> és a
	  <makevar>DOC</makevar> változónak van
	  értéke.</para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title>A <filename>doc.project.mk</filename>
	állomány</title>

      <para>Nézzünk bele:</para>

      <programlisting>DOCFORMAT?=	docbook
MAINTAINER?=	doc@FreeBSD.org

PREFIX?=	/usr/local
PRI_LANG?=	en_US.ISO8859-1

.if defined(DOC)
.if ${DOCFORMAT} == "docbook"
.include "doc.docbook.mk"
.endif
.endif

.include "doc.subdir.mk"
.include "doc.install.mk"</programlisting>

      <sect3>
	<title>Változók</title>

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

	<para>A <makevar>PREFIX</makevar> adja azt a
	  könyvtárat, amelyen belül
	  elérhetõek <link linkend="tools">a
	    dokumentáció
	    elõállításához
	    szükséges eszközök</link>.
	  A csomagok és portok átlagos használata
	  esetén ez a <filename>/usr/local</filename>.</para>

	<para>A <makevar>PRI_LANG</makevar> 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.</para>

	<note>
	  <para>A <makevar>PRI_LANG</makevar> változó
	    semmilyen hatással nincs a dokumentumok
	    elõállítására.
	    Egyedül a &os; dokumentáció
	    telepítésekor a leggyakrabban hivatkozott
	    dokumentumokhoz létrehozandó szimbolikus
	    linkek készítésénel van
	    szerepe.</para>
	</note>
      </sect3>

      <sect3>
	<title>Elágazások</title>

	<para>A <literal>.if defined(DOC)</literal> sorban a
	  <filename>Makefile</filename> állományokban
	  megadható elágazásokra láthatunk
	  példát.  Hasonlóan más
	  programokhoz, a <filename>Makefile</filename>
	  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 <literal>defined</literal>
	  függvény, amely megadja, hogy a
	  paramétereként megadott változó
	  definiált-e.</para>

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

	<para>Az elõbb említett két
	  elágazást rendre az <literal>.endif</literal>
	  kulcsszóval zárjuk le.</para>
      </sect3>
    </sect2>

    <sect2>
      <title>A <filename>doc.subdir.mk</filename>
	állomány</title>

      <para>Ez az állomány már
	túlságosan nagy ahhoz, hogy a fejezeten belül
	könnyen ki lehessen elemezni.  Ezért az
	elõzõ szakaszok alapján a részleteket a
	kedves Olvasóra bízzuk, ehhez adunk még itt
	némi segítséget.</para>

      <sect3>
	<title>Változók</title>

	<itemizedlist>
	  <listitem>
	    <para>A <makevar>SUBDIR</makevar> tartalmazza azokat az
	      alkönyvtárakat, amelyeket a feldolgozás
	      során be kell járnunk.</para>
	  </listitem>

	  <listitem>
	    <para>A <makevar>ROOT_SYMLINKS</makevar> a
	      dokumentáció
	      fõkönyvtárából
	      szimbolikusan linkelendõ könyvtárak
	      neveit adja meg, amennyiben az adott nyelv (a
	      <makevar>PRI_LANG</makevar> változó szerint)
	      az elsõdleges.</para>
	  </listitem>

	  <listitem>
	    <para>A <makevar>COMPAT_SYMLINK</makevar>
	      változót már korábban bemutattuk
	      <link linkend="sub-make">az alkönyvtári
	      <filename>Makefile</filename>
	      állományok</link> címû
	      szakaszban.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Célok és makrók</title>

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

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

	<para>A <literal>.USE</literal> nevû speciális
	  függõség egy makróval
	  egyenértékû eszköz
	  használatára ad lehetõséget.</para>

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

	<para>A fenti kódrészletben tehát a
	  <maketarget>_SUBDIRUSE</maketarget> most már egy
	  <quote>makró</quote> lesz, amely ha megjelenik a
	  függõségek között, akkor a
	  törzsében megadott parancsokat hajtja
	  végre.</para>

	<para>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 <emphasis>után</emphasis>
	  fognak lefutni, másrészt nem befolyásolja
	  a jelenleg feldolgozás alatt álló
	  cél nevét tároló
	  <makevar>.TARGET</makevar> változó
	  értékét.</para>

<programlisting>clean: _SUBDIRUSE
	rm -f ${CLEANFILES}</programlisting>

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

	<sect4>
	  <title>Definiált célok</title>

	  <itemizedlist>
	    <listitem>
	      <para>Az <maketarget>install</maketarget> és a
		<maketarget>package</maketarget> célok
		egyaránt folyamatosan haladnak lefelé a
		könyvtárszerkezetben és az
		alkönyvtárakban hívják
		saját maguk tényleges
		változatát (ezek a
		<maketarget>realinstall</maketarget> és
		<maketarget>realpackage</maketarget>).</para>
	    </listitem>

	    <listitem>
	      <para>A <maketarget>clean</maketarget>
		eltávolítja a folyamat során
		keletkezett állományokat (és az
		elõbbiekhez hasonlóan lefele halad a
		könyvtárszerkezetben).  A
		<maketarget>cleandir</maketarget> ugyanezt
		csinálja, de ha talál a
		tárgykódokhoz tartozó
		könyvtárat, akkor azt is törli.</para>
	    </listitem>
	  </itemizedlist>
	</sect4>
      </sect3>

      <sect3>
	<title>Bõvebben a feltételes
	  kifejezésekrõl</title>

	<itemizedlist>
	  <listitem>
	    <para>Az <literal>exists</literal> egy másik logikai
	      függvény, amellyel lekérdezhetjük,
	      hogy a paramétereként megadott
	      állomány létezik-e.</para>
	  </listitem>

	  <listitem>
	    <para>Az <literal>empty</literal> logikai
	      függvény igaz értékû, ha a
	      paramétereként megadott
	      változó értéke
	      üres.</para>
	  </listitem>

	  <listitem>
	    <para>A <literal>target</literal> logikai
	      függvény igaz értékû, ha a
	      paraméterként megadott cél még
	      nem létezik.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Ciklusszerverzési lehetõségek
	  (<literal>.for</literal>)</title>

	<para>A <literal>.for</literal> 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.</para>

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

	<para>A fenti kódrészletben ha a
	  <makevar>SUBDIR</makevar> üres, akkor nem
	  történik semmi.  Ha viszont egy vagy több
	  elemet is tartalmaz, akkor a <literal>.for</literal> és
	  az <literal>.endfor</literal> 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 <makevar>entry</makevar>
	  változóban veszi fel.</para>
      </sect3>
    </sect2>
  </sect1>
</chapter>