diff --git a/hu_HU.ISO8859-2/books/fdp-primer/writing-style/chapter.sgml b/hu_HU.ISO8859-2/books/fdp-primer/writing-style/chapter.sgml index 33fc0bcbff..6de288dd69 100644 --- a/hu_HU.ISO8859-2/books/fdp-primer/writing-style/chapter.sgml +++ b/hu_HU.ISO8859-2/books/fdp-primer/writing-style/chapter.sgml @@ -1,664 +1,664 @@ A fogalmazás stílusa 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. Az angol nyelvû dokumentáció írásakor az amerikai angol szerinti helyesírást használjuk! 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 color és nem colour, rationalize és nem rationalise, stb. 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. Ne rövidítsünk! Ne alkalmazzunk rövidítéseket a szövegben. Mindig minden kifejezést, szót írjunk ki teljes alakjában. Pl. ez a példa tehát nem helyes. Angol nyelven mindez az összevonások elkerülésére vonatkozik, tehát a formális fogalmazási stílusra. 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. A felsorolásoknál tegyünk ki vesszõket! 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 and (és) szóval. A magyarban figyeljünk arra, hogy ez elé már nem kell vesszõ. Például tekintsük a következõ mondatot:
This is a list of one, two and three items.
Magyarul:
Ez a lista egy, két és három elembõl áll.
Az angol változat esetén felvetõdhet a kérdés, hogy ez a lista most egy, két és három elembõl áll, vagy egy, két és három elembõl. Ezért itt az utolsó tag elõtt is ki kell tenni a vesszõt:
This is a list of one, two, and three items.
Kerüljük a szóismétlést! Lehetõség szerint törekedjünk a szóismétlések elkerülésére. Ez konkrétan a a parancs, az állomány és man parancs 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. 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. Use the command cvsup to update your sources. Use cvsup to update your sources. 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: A forrásainkat a cvsup paranccsal frissítsük. 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: A cvsup segítségével frissítsük a forrásainkat. 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: … in the filename /etc/rc.local… … in /etc/rc.local… A magyarban szintén a korábbiak érvényesek. A most következõ példákban man hivatkozásokat láthatunk. Közülük ismét a második lesz a javasolt: See man csh for more information. See &man.csh.1;. A magyar fordításban: Lásd &man.csh.1;. Vagy: Lásd a &man.csh.1; man oldalt. Mindig hagyjunk két szóközt a mondatok között! 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 Emacs és a hozzá hasonló eszközök használatát. 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 Jordan K. Hubbard. Ebben a névben középen található egy H, 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. Az angol nyelvû fogalmazási stílus szabályairól részletesebb bemutatást William Strunk Elements of Style címû könyvébõl kaphatunk. A forráskód stílusa 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. Kis- és nagybetûk A címkéket soha ne nagybetûkkel, hanem mindig kisbetûkkel írjuk, például para és nem PARA. Az SGML környezetekben megjelenõ szövegeket viszont általában nagybetûvel kell írni, például <!ENTITY…>, <!DOCTYPE…>, és nem <!entity…> vagy <!doctype…>. Mozaikszavak A mozaikszavakat elsõ alkalommal általában illik rendesen kiírni, például: Network Time Protocol (NTP). 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. A mozaikszavak elsõ három megjelenését az acronym elemmel kell jelölni, ahol egy role 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. Tördelés Mindegyik forrás tördelése a nulladik oszloptól indul, függetlenül attól, hogy az adott állományt milyen más állomány fogja késõbb tartalmazni. 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. Például ennek a szakasznak így néz ki a szabályos tördelése: +--- Ez a nulladik oszlop V <chapter> <title>...</title> <sect1> <title>...</title> <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ány milyen más állomány fogja késõbb tartalmazni.</para> ... </sect2> </sect1> </chapter> Ha az Emacs vagy XEmacs szerkesztõkkel dolgozunk, akkor az állományok megnyitásakor automatikusan be kellene töltõdnie az sgml-mode 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. A Vim szerkesztõvel dolgozóknak pedig a következõ beállításokat javasoljuk: 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 A címkék stílusa 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> 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. Változtatások a forrás tördelésén A források változtatása során ügyeljünk arra, hogy sose tároljunk egyszerre a repositoryba tartalmat és tördelést érintõ módosításokat. 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. 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 (whitespace-only change). Így a fordítók tudni fogják, hogy ezt figyelmen kívül kell hagyniuk. Nem törhetõ szóközök 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: Az adattároló kapacitása általában 40 MB és 15 GB között változik. Hardveres tömörítéssel … Az &nbsp; általános egyed viszont megtiltja az egymáshoz szorosan kötõdõ elemek közti sortörést. Az ilyen nem törhetõ szóközök használatát elsõsorban a következõ helyeken javasoljuk: mennyiségek és egységek között: program neve és verziószáma között: több szóból álló nevek esetén (óvatosan bánjunk ezzel viszont olyan hosszabb neveknél, mint például a The &os; Brazilian Portugese Documentation Project): Szólista 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 O'Reilly-féle gyûjteményt. 2.2.X 4.X-STABLE CD-ROM DoS (Denial of Service) Ports Collection IPsec Internet MHz Soft Updates Unix disk label email file system manual page mail server name server null-modem web server