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 &os; 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:

1. Készítsünk másolatot az eredeti állományról. Mielõtt az ize.sgml állományt módosítanánk, végezzük el a következõ mûveletet:

   	  % cp ize.sgml ize.sgml.eredeti
   	

2. Ezt követõen végezzük el a kívánt módosításokat az ize.sgml állományon.

   	  % vi foo.sgml
   	  ... tap tap tap ...
   	  ... teszteljük a módosításokat, nézzük át, nehogy
   	  elírás maradjon benne stb. ...
   	

3. Készítsük el a diffet. Ehhez a következõ parancsot kell kiadnunk:

   	  % diff -u ize.sgml.eredeti ize.sgml > 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.