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.
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.
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 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:
<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>
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):
<questions@FreeBSD.org>.
Ha ezzel a dokumentummal kapcsolatban van kérdése, kérjük erre a címre írjon:
<gabor@FreeBSD.org>.