doc/hu_HU.ISO8859-2/books/fdp-primer/writing-style/chapter.xml
Gabor Kovesdan b4346b9b2d - Rename .sgml files to .xml
- Reflect the rename in referencing files

Approved by:	doceng (implicit)
2012-10-01 09:53:01 +00:00

652 lines
18 KiB
XML

<?xml version="1.0" encoding="iso-8859-2"?>
<!-- Copyright (c) 1998 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/writing-style/chapter.xml
%SRCID% 1.49
-->
<chapter id="writing-style" lang="hu">
<title>A fogalmazás stílusa</title>
<para>A &os; dokumentációját
készítõ rengeteg író
munkájának összehangolására ebben a
fejezetben megadunk néhány követendõ
alapelvet.</para>
<variablelist>
<varlistentry>
<term>Az angol nyelvû dokumentáció
írásakor az amerikai angol szerinti
helyesírást használjuk!</term>
<listitem>
<para>A szavak helyesírását tekintve az
angolnak több különbözõ
változata létezik. Vitás helyzetekben az
egységesség kedvéért ezért
mindig az amerikai helyesírást tekintsük
irányadónak. Ennek megfelelõen
tehát <quote>color</quote> és nem
<quote>colour</quote>, <quote>rationalize</quote> és
nem <quote>rationalise</quote>, stb.</para>
<note>
<para>A brit angol használata elfogadott lehet
beküldött cikkek esetében, viszont ilyenkor a
helyesírásnak egységesnek kell lennie a
teljes dokumentumon belül. Az összes többi
dokumentum, tehát könyvek, honlapok, man oldalak
stb. esetén azonban mindig amerikai angolt kell
alkalmazni.</para>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term>Ne rövidítsünk!</term>
<listitem>
<para>Ne alkalmazzunk rövidítéseket a
szövegben. Mindig minden kifejezést, szót
írjunk ki teljes alakjában. <quote>Pl. ez a
példa</quote> tehát nem helyes. Angol nyelven
mindez az összevonások
elkerülésére vonatkozik, tehát a
formális fogalmazási stílusra.</para>
<para>A rövidítések
elhagyásával könnyebb a szövegnek
formális jelleget adni, így sokkal
precízebben megfogalmazott, a fordítók
számára is érthetõbb mondatokat
nyerünk.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A felsorolásoknál tegyünk ki
vesszõket!</term>
<listitem>
<para>Angol nyelven, ha több elemet sorolunk fel egyetlen
bekezdésben, akkor ezeket mindig vesszõkkel kell
tagolnunk. Az utolsó elemnél mindezt
egészítsük ki még egy
<quote>and</quote> (<quote>és</quote>) szóval.
A magyarban figyeljünk arra, hogy ez elé
már nem kell vesszõ.</para>
<para>Például tekintsük a következõ
mondatot:</para>
<blockquote>
<para>This is a list of one, two and three items.</para>
</blockquote>
<para>Magyarul:</para>
<blockquote>
<para>Ez a lista egy, két és három
elembõl áll.</para>
</blockquote>
<para>Az angol változat esetén felvetõdhet a
kérdés, hogy ez a lista most <quote>egy</quote>,
<quote>két</quote> és
<quote>három</quote> elembõl áll, vagy
<quote>egy</quote>, <quote>két és
három</quote> elembõl.</para>
<para>Ezért itt az utolsó tag elõtt is ki
kell tenni a vesszõt:</para>
<blockquote>
<para>This is a list of one, two, and three items.</para>
</blockquote>
</listitem>
</varlistentry>
<varlistentry>
<term>Kerüljük a
szóismétlést!</term>
<listitem>
<para>Lehetõség szerint törekedjünk a
szóismétlések
elkerülésére. Ez konkrétan a
<quote>a parancs</quote>, <quote>az
állomány</quote> és <quote>man
parancs</quote> jellegû kifejezések
mellõzését jelenti, mert ezek sokszor
feleslegesen szerepelnek a szövegben. A magyar
fordításban azonban néha hasznosnak
bizonyulnak, különösen a
ragozásban.</para>
<para>Most mutatunk két példát a
parancsokra. Ezek közül a másodikban
bemutatott stílust javasoljuk az angol szövegek
esetén.</para>
<informalexample>
<para>Use the command <command>cvsup</command> to update your
sources.</para>
</informalexample>
<informalexample>
<para>Use <command>cvsup</command> to update your sources.</para>
</informalexample>
<para>A magyar szövegben viszont ennek
tökéletesen elfogadott a következõ
típusú fordítása, mivel így
könnyebb ragozni a parancsot:</para>
<informalexample>
<para>A forrásainkat a <command>cvsup</command>
paranccsal frissítsük.</para>
</informalexample>
<para>Ha a magyarban is el akarjuk kerülni minden
áron az ilyen jellegû ismétléseket,
akkor próbálkozhatunk úgy írni a
mondatot, hogy ne kelljen az idegen szót
ragoznunk:</para>
<informalexample>
<para>A <command>cvsup</command>
segítségével frissítsük a
forrásainkat.</para>
</informalexample>
<para>Az alábbi példákban az
állományok neveire láthatunk
példákat, amelyek közül ismét a
másodikat javasoljuk az angol nyelv
esetén:</para>
<informalexample>
<para>&hellip; in the filename
<filename>/etc/rc.local</filename>&hellip;</para>
</informalexample>
<informalexample>
<para>&hellip; in
<filename>/etc/rc.local</filename>&hellip;</para>
</informalexample>
<para>A magyarban szintén a korábbiak
érvényesek.</para>
<para>A most következõ példákban man
hivatkozásokat láthatunk. Közülük
ismét a második lesz a javasolt:</para>
<informalexample>
<para>See <command>man csh</command> for more
information.</para>
</informalexample>
<informalexample>
<para>See &man.csh.1;.</para>
</informalexample>
<para>A magyar fordításban:</para>
<informalexample>
<para>Lásd &man.csh.1;.</para>
</informalexample>
<para>Vagy:</para>
<informalexample>
<para>Lásd a &man.csh.1; man oldalt.</para>
</informalexample>
</listitem>
</varlistentry>
<varlistentry>
<term>Mindig hagyjunk két szóközt a mondatok
között!</term>
<listitem>
<para>A mondatok végén mindig hagyjunk két
szóköznyi helyet. Ezáltal javul a
szöveg olvashatósága, valamint
megkönnyíti az <application>Emacs</application>
és a hozzá hasonló eszközök
használatát.</para>
<para>Habár vitatható, hogy ez a
megkülönböztetés egyáltalán
szükséges-e, bizonyos esetekben valóban
hasznos lehet, különösen neveknél. Erre
remek példa <quote>Jordan K. Hubbard</quote>. Ebben a
névben középen található egy
<literal>H</literal>, amelyet a mondat végéhez
hasonlóan egy pont és egy szóköz
követ, viszont jól látható, hogy itt
nem ér véget a mondat.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Az angol nyelvû fogalmazási stílus
szabályairól részletesebb bemutatást
William Strunk <ulink
url="http://www.bartleby.com/141/">Elements of Style</ulink>
címû könyvébõl kaphatunk.</para>
<sect1 id="writing-style-guide">
<title>A forráskód stílusa</title>
<para>Mivel a dokumentáció forrását
egyszerre többen szerkesztik, valamilyen módon
egységes formában kell tartani. Ennek
érdekében legyünk szívesek az
alábbiakban megadott iránymutatások szerint
dolgozni.</para>
<sect2>
<title>Kis- és nagybetûk</title>
<para>A címkéket <emphasis>soha ne</emphasis>
nagybetûkkel, hanem mindig kisbetûkkel írjuk,
például <sgmltag>para</sgmltag> és
<emphasis>nem</emphasis> <sgmltag>PARA</sgmltag>.</para>
<para>Az SGML környezetekben megjelenõ szövegeket
viszont általában nagybetûvel kell írni,
például <literal>&lt;!ENTITY&hellip;&gt;</literal>,
<literal>&lt;!DOCTYPE&hellip;&gt;</literal>, és
<emphasis>nem</emphasis>
<literal>&lt;!entity&hellip;&gt;</literal> vagy
<literal>&lt;!doctype&hellip;&gt;</literal>.</para>
</sect2>
<sect2>
<title>Mozaikszavak</title>
<para>A mozaikszavakat elsõ alkalommal
általában illik rendesen kiírni,
például: <quote>Network Time Protocol (<acronym
role="Network Time Protocol">NTP</acronym>)</quote>.
Miután definiáltuk a mozaikszó
mögött álló jelentést,
elegendõ csak a rövidített alakot
használni (nem kell tehát a teljes
kifejezést, kivéve, ha az adott
szövegkörnyezetben annak több értelme
van). A mozaikszavakat dokumentumonként egyszer
definiáljuk. Ha viszont nekünk jobban megfelel,
akkor akár fejezetenként is kifejthetjük az
egyes mozaikszavakat.</para>
<para>A mozaikszavak elsõ három
megjelenését az <sgmltag>acronym</sgmltag> elemmel
kell jelölni, ahol egy <literal>role</literal>
tulajdonságban megadjuk a mögött
álló teljes kifejezést. Ennek
köszönhetõen a dokumentumok feldolgozása
során létre lehet hozni szószedetet az
alkalmazott rövidítésékhez, illetve a
honlapokon meg lehet oldani, hogy ha az egérrel
felé visszük a kurzort, megjelenjen a teljes
megnevezés.</para>
</sect2>
<sect2>
<title>Tördelés</title>
<para>Mindegyik forrás tördelése a nulladik
oszloptól indul, <emphasis>függetlenül</emphasis>
attól, hogy az adott állományt milyen
más állomány fogja késõbb
tartalmazni.</para>
<para>A nyitócímkék után két
szóközzel kell bentebb húzni a szöveget.
Ennek megfelelõen a zárócímkék
pedig két szóközzel csökkentik az
aktuális behúzás
mértékét. A sorok elején
szereplõ szóközöket nyolcas csoportban
cseréljünk tabulátorokra. Ne
használjunk szóközöket a
tabulátorok elõtt, és ne tegyünk
további szóközöket a sorok
végére. Ha az elemek tartalma egy sornál
hosszabb, akkor a következõ sort az elem
nyitócímkéjéhez képest mindig
két szóközzel bentebb kell kezdeni.</para>
<para>Például ennek a szakasznak így
néz ki a szabályos tördelése:</para>
<programlisting>+--- Ez a nulladik oszlop
V
&lt;chapter>
&lt;title>...&lt;/title>
&lt;sect1>
&lt;title>...&lt;/title>
&lt;sect2>
&lt;title>Tördelés&lt;/title>
&lt;para>Mindegyik forrás tördelése a nulladik oszloptól indul,
&lt;emphasis>függetlenül&lt;/emphasis> attól, hogy az adott állomány
milyen más állomány fogja késõbb tartalmazni.&lt;/para>
...
&lt;/sect2>
&lt;/sect1>
&lt;/chapter></programlisting>
<para>Ha az <application>Emacs</application> vagy
<application>XEmacs</application> szerkesztõkkel dolgozunk,
akkor az állományok megnyitásakor
automatikusan be kellene töltõdnie az
<literal>sgml-mode</literal>
kiegészítésnek, illetve az egyes
források végén található
változók pontosan a fenti szabályok
betartatásáról gondoskodnak.</para>
<para>A <application>Vim</application> szerkesztõvel
dolgozóknak pedig a következõ
beállításokat javasoljuk:</para>
<programlisting>augroup sgmledit
autocmd FileType sgml set formatoptions=cq2l " Speciális formázási beállítások
autocmd FileType sgml set textwidth=70 " Legfeljebb 70 oszlop széles sorok
autocmd FileType sgml set shiftwidth=2 " Az automatikus behúzás mértéke
autocmd FileType sgml set softtabstop=2 " A tabulátor 2 szóközzel visz bentebb
autocmd FileType sgml set tabstop=8 " 8 szóköz cseréje egy tabulátorra
autocmd FileType sgml set autoindent " Automatikus behúzás
augroup END</programlisting>
</sect2>
<sect2>
<title>A címkék stílusa</title>
<sect3>
<title>A címkék elrendezése</title>
<para>Az egy behúzási szinten
található címkéket mindig
válasszuk el egy üres sorral, a többi esetben
viszont ne:</para>
<informalexample>
<programlisting>&lt;article>
&lt;articleinfo>
&lt;title>NIS&lt;/title>
&lt;pubdate>1999 október&lt;/pubdate>
&lt;abstract>
&lt;para>...
...
...&lt;/para>
&lt;/abstract>
&lt;/articleinfo>
&lt;sect1>
&lt;title>...&lt;/title>
&lt;para>...&lt;/para>
&lt;/sect1>
&lt;sect1>
&lt;title>...&lt;/title>
&lt;para>...&lt;/para>
&lt;/sect1>
&lt;/article></programlisting>
</informalexample>
</sect3>
<sect3>
<title>A címkék tagolása</title>
<para>Bizonyos címkék, mint például
az <sgmltag>itemizedlist</sgmltag>, amelyekben további
címkék szerepelnek és nem karakteres
adat, mindig egyedül állnak egy sorban.</para>
<para>A <sgmltag>para</sgmltag> és
<sgmltag>term</sgmltag> 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, <emphasis>ugyanabban a
sorban</emphasis>.</para>
<para>Ugyanez érvényes az említett
címketípusok zárásakor.</para>
<para>A címketípusok keveredése egy
nyilvánvaló problémát
eredményez.</para>
<para>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.</para>
<para>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.</para>
</sect3>
</sect2>
<sect2>
<title>Változtatások a forrás
tördelésén</title>
<para>A források változtatása során
ügyeljünk arra, hogy <emphasis>sose tároljunk
egyszerre a repositoryba tartalmat és
tördelést érintõ
módosításokat</emphasis>.</para>
<para>Ennek köszönhetõen a
dokumentációt fordító csapatok
könnyebben észreveszik, hogy mi változott a
módosításunk nyomán. Így nem
kell azon gondolkozniuk, hogy vajon most tényleg
változott a tartalom, vagy csak
újratördeltük a sorokat.</para>
<para>Például ha felvettünk két mondatot
még egy bekezdéshez, és ezzel az adott
bekezdés sorainak hossza túlságosan
megnõtt, akkor elõször tároljuk a
hosszú sorokat tartalmazó változatot.
Ezután végezzük el a szükséges
tördelést és tároljuk azt a
változatot is. Ez utóbbi esetben azonban ne
felejtsük egyértelmûen jelezni a
tároláshoz tartozó üzenetben, hogy
csak a tördelésen változtattunk
(<quote>whitespace-only change</quote>). Így a
fordítók tudni fogják, hogy ezt figyelmen
kívül kell hagyniuk.</para>
</sect2>
<sect2>
<title>Nem törhetõ szóközök</title>
<para>Lehetõleg kerüljük a sortöréseket
olyan helyeken, ahol csúnyán néznének
ki, vagy rontanának a szöveg
olvashatóságán. A sortörések
mindig a kimeneti formátum által alkalmazott
sorszélességtõl függenek.
Különösen a HTML oldalakon
található formázott bekezdések
jelennek meg ízléstelenül egy szöveges
böngészõben, mint például ez
is:</para>
<literallayout class="monospaced">Az adattároló kapacitása általában 40 MB és 15
GB között változik. Hardveres tömörítéssel &hellip;</literallayout>
<para>Az <literal>&amp;nbsp;</literal> általános
egyed viszont megtiltja az egymáshoz szorosan
kötõdõ elemek közti sortörést.
Az ilyen <quote>nem törhetõ</quote>
szóközök használatát
elsõsorban a következõ helyeken
javasoljuk:</para>
<itemizedlist>
<listitem>
<para>mennyiségek és egységek
között:</para>
<programlisting><![CDATA[57600&nbsp;bps]]></programlisting>
</listitem>
<listitem>
<para>program neve és verziószáma
között:</para>
<programlisting><![CDATA[FreeBSD&nbsp;7.1]]></programlisting>
</listitem>
<listitem>
<para>több szóból álló nevek
esetén (óvatosan bánjunk ezzel viszont
olyan hosszabb neveknél, mint például a
<quote>The &os; Brazilian Portugese Documentation
Project</quote>):</para>
<programlisting><![CDATA[Sun&nbsp;Microsystems]]></programlisting>
</listitem>
</itemizedlist>
</sect2>
</sect1>
<sect1 id="writing-style-word-list">
<title>Szólista</title>
<para>Ebben a rövid szólistában
összefoglalunk néhány angol szót a &os;
Dokumentációs Projektben alkalmazandó
írásmódjuk szerint. Ha a keresendõ
szó nem szerepel ebben a felsorolásban,
nézzük meg az <ulink
url="http://www.oreilly.com/oreilly/author/stylesheet.html">O'Reilly-féle
gyûjteményt</ulink>.</para>
<itemizedlist>
<listitem>
<para>2.2.X</para>
</listitem>
<listitem>
<para>4.X-STABLE</para>
</listitem>
<listitem>
<para>CD-ROM</para>
</listitem>
<listitem>
<para>DoS <emphasis>(Denial of Service)</emphasis> </para>
</listitem>
<listitem>
<para>Ports Collection</para>
</listitem>
<listitem>
<para>IPsec</para>
</listitem>
<listitem>
<para>Internet</para>
</listitem>
<listitem>
<para>MHz</para>
</listitem>
<listitem>
<para>Soft Updates</para>
</listitem>
<listitem>
<para>Unix</para>
</listitem>
<listitem>
<para>disk label</para>
</listitem>
<listitem>
<para>email</para>
</listitem>
<listitem>
<para>file system</para>
</listitem>
<listitem>
<para>manual page</para>
</listitem>
<listitem>
<para>mail server</para>
</listitem>
<listitem>
<para>name server</para>
</listitem>
<listitem>
<para>null-modem</para>
</listitem>
<listitem>
<para>web server</para>
</listitem>
</itemizedlist>
</sect1>
</chapter>