1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
|
<?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.sgml
%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/sgml</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.sgml</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.sgml</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.sgml</filename></title>
<para>A kézikönyv egyes fejezetei
egymástól különálló
könyvtárakban, <filename>chapter.sgml</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.sgml</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.sgml</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.sgml</filename>
állománnyal. Például
<filename>basics/chapter.sgml</filename>,
<filename>introduction/chapter.sgml</filename> és
<filename>printing/chapter.sgml</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.sgml</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>
|