A FreeBSD Dokumentációs Projekt: Dokumentáció beküldése
Hogyan lehet beküldeni dokumentációt?
Elõször is szeretnénk megköszönni, hogy erre fordítottuk az idõnket!
Az elkészített dokumentációt valamilyen módon elérhetõvé kell tenni. Amennyiben lehetséges, helyezzünk el egy FTP oldalon vagy webcímen.
Ezt követõen írjunk levelet a freebsd-doc
levelezési listára, amelyben röviden ismertetjük a dokumentációt és
hivatkozunk a pontos helyére, majd várjunk a visszajelzésre.
Amennyiben valamilyen okból kifolyólag nem áll módunkban
elhelyezni a dokumentációt FTP vagy webhelyen, közvetlenül is
elküldhetjük a freebsd-doc
levelezési lista címére is.
Ebben az esetben viszont lehetõleg csak egyszerû szöveges
dokumentumokat küldjünk.
Elõfordulhat, hogy más levelezési listákon is megvitatnák a
dokumentációt, tehát érdemes azokra is elküldeni egy másolatot
belõle. Például egy olyan cikk, amely arról szól, hogy a CVSup
hogyan tarthatjuk a forrásainkat frissen, további érdeklõdésre
tarthat számot a freebsd-current
és a
freebsd-stable
listákon is.
Miután a dokumentációt átnézték, tegyünk eleget a vele kapcsolatban beérkezett javaslatoknak, és már készen is áll a közzétételre.
Ehhez nem kell mást tennünk, csak csomagoljuk be egy tar
állományba. Ha például tehát a dokumentáció három állományból áll,
mint az elso
, masodik
, illetve
harmadik
, és ezekbõl szeretnénk egyetlen
doc.tar
állományt készíteni, akkor adjuk ki az ehhez
szükséges parancsot:
% tar cf doc.tar elso masodik harmadik
Ezután tömörítsük az így kapott tar állományt az alábbi paranccsal:
% gzip -9 doc.tar
Így elõáll a doc.tar.gz
tömörített állomány.
Végül pedig kódoljuk az állományt, nehogy véletlenül egy levelezõprogram szétcincálja.
% uuencode doc.tar.gz doc.tar.gz > doc.uue
Ezt követõen tudatnunk kell a Dokumentációs Projekttel az új dokumentáció létezését. Ennek megfelelõ módja a send-pr parancs használata, amely valószínûleg már el is érhetõ a számítógépünkön. Erre viszont a hibajelentõ ûrlapot is használhatjuk.
Erre azért van szükség, hogy a munka követhetõ legyen. Mikor jelentünk egy problémát, az egy egyedi azonosítót kap. Valamelyik committer ezt követõen magához rendeli a hibajelentést és a részletek tisztázása érdekében felveszi velünk a kapcsolatot. Erre vonatkozóan olvassuk el a FreeBSD hibajelentések írása címû cikket.
A send-pr program meglehetõsen egyszerû. Feladata, hogy egy megfelelõ formátumú e-mailt küldjön a megfelelõ címre. Mikor elindítjuk a send-pr programot, az alapértelmezett szövegszerkesztõ (a vi vagy az emacs) kerül betöltésre egy kitöltendõ formanyomtatvánnyal és a kitöltést elõsegítõ kevés leírással.
Gyõzõdjünk meg róla, hogy a "Category" mezõben a "docs", a
"Class" mezõben pedig a "change-request" szerepel, továbbá
szükséges, hogy az elõzõleg elkészített .uue
állomány
tartalmát is beillesszünk a hibajelentésbe.
A szövegszerkesztõbõl kilépve a hibajelentést a program e-mailként elküldi a megfelelõ helyre. Rövid idõvel ezután értesítést fog kapni a hibajelentés egyedi azonosítójáról, amivel nyomon tudjuk követni a beküldés hibajelentés állapotát.
Hova lehet küldeni a már létezõ dokumentációkon végzett módosításokat?
Elõször is ismét megköszönnénk, hogy erre fordítottuk az idõt.
Ebben az esetben készíteni kell egy speciális diff állományt, amely csak az általunk javasolt változtatásokat tartalmazza. Ez leegyszerûsíti a committer dolgát, mivel így könnyebben átlátja, hogy mit szeretnénk változtatni, és nekünk sem kell hosszasan magyaráznunk, hogy milyen részleteket írtunk át (amellett természetesen, hogy megindokoljuk, miért van szükség a javasolt változtatások elvégzésére).
A 'diff' állomány készítéséhez a következõket kell tennünk:
-
Készítsünk másolatot az eredeti állományról. Mielõtt az
ize.xml
állományt módosítanánk, végezzük el a következõ mûveletet:% cp ize.xml ize.xml.eredeti
-
Ezt követõen végezzük el a kívánt módosításokat az ize.xml állományon.
% vi foo.xml ... tap tap tap ... ... teszteljük a módosításokat, nézzük át, nehogy elírás maradjon benne stb. ...
-
Készítsük el a diffet. Ehhez a következõ parancsot kell kiadnunk:
% diff -u ize.xml.eredeti ize.xml > ize.diff
A program megvizsgálja a két állomány közti eltéréseket, és az
ize.diff
állományba írja azokat.
Ezután már küldhetjük is az ize.diff
állományt a
projektnek. Az elõzõleg tárgyaltaknak megfelelõen írjunk egy
hibajelentést, de a levél törzsébe az ize.diff
tartalmát illesszük.