A FreeBSD 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.
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.
Megjegyzés: 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 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.
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.
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.
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:
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:
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:
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 csh(1).
A magyar fordításban:
Lásd csh(1).
Vagy:
Lásd a csh(1) man oldalt.
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.
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.
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...>.
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.
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
Az egy behúzási szinten található címkéket mindig válasszuk el egy üres sorral, a többi esetben viszont ne:
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.
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.
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 á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:
57600 bps
program neve és verziószáma között:
FreeBSD 7.1
több szóból álló nevek esetén (óvatosan bánjunk ezzel viszont olyan hosszabb neveknél, mint például a “The FreeBSD Brazilian Portugese Documentation Project”):
Sun Microsystems
Ha kérdése van a FreeBSD-vel kapcsolatban, a következő
címre írhat (angolul): <freebsd-questions@FreeBSD.org>.
Ha ezzel a dokumentummal kapcsolatban van kérdése,
kérjük erre a címre írjon: <gabor@FreeBSD.org>.