~ubuntu-hu-doc/ubuntu-hu-doc/karmic

Referencia dokumentáció
=======================

Miről szól a referencia dokumentáció
------------------------------------
Ezen útmutató segítségével megtanulhatod, hogy hogyan vehetsz részt az ubuntu
dokumentációs csoport munkájában, hogyan kell kinéznie egy ubuntu.hu_ oldalon
megjelenő hivatalos dokumentációnak, valamint hogy hogyan használhatod a bazaar
verziókezelő rendszert a munka során. A dokumentum megmutatja, hogyan írhatsz
hasonlóan egységes útmutatókat, mint amilyeneket a **Rendszer → Segítség és
támogatás** menüpontban találhatsz, és hogyan tarthatod ezeket karban, a
többiekkel együttműködve.

Hogyan kezdj bele
-----------------

Telepítsd fel a *python-docutils*, a *bzr* és a *bzr-gtk* csomagokat:

``sudo aptitude install python-docutils bzr bzr-gtk``

Hogyan írj dokumentációt
------------------------
Ebben a dokumentumban összegyűjtöttük a legfontosabb irányelveket, ajánlásokat
és tudnivalókat a dokumentációkat, útmutatókat készítők számára. Kérjük, ezeket
tartsd szem előtt, amikor dolgozol:

Törekedj az érthető fogalmazásra, és az egyértelmű terminológiára.

Figyelj oda a helyesírásra, nyelvhelyességre és az áttekinthető tördelésre.

Ahol lehet, használj magyar kifejezéseket - de nem mindenáron: ha a
gyakorlatban az angol kifejezés terjedt el (például kernel) használd nyugodtan
azt.

Mindig a magyar felhasználói felület kifejezéseid használd - kivéve, ahol ez
értelemszerűen nem lehetséges (mert az adott alkalmazás nem érhető el magyar
nyelven), vagy értelmetlen lenne (például arról írsz, hogy hogyan lehet egy
angol rendszerre a magyar nyelvi támogatást telepíteni utólag).

Grafikus felületen a **synaptic**, konzolon az **aptitude** a preferált
csomagkezelő, így a leírásokban is ezek szerepeljenek.

Az alapértelmezett disztribúció az Ubuntu. Vagyis hacsak nem kifejezetten
Kubuntu vagy Xubuntu specifikus a téma, akkor mindig az Ubuntu-t vedd alapul,
és erről készüljenek a képernyőképek is.

Grafikus alkalmazásokat grafikus csomagkezelővel (synaptic), konzolos
alkalmazásokat konzolos csomagkezelővel (aptitude) telepítsd.

Külső forrásból származó csomagokat csak akkor használj, ha ez *tényleg*
elkerülhetetlen (például ABEVJava).

Konzolos alkalmazásokat a ``sudo``, grafikus alkalmazásokat a ``gksu``
(Ubuntu és Xubuntu esetében) vagy a ``kdesudo`` (Kubuntu esetében) paranccsal
indítsd, ha rendszergazdai jogosultságot igényelnek. Vagyis ``sudo nano ...``
vagy ``gksu gedit ...``, esetleg ``kdesudo kate ...`` - tehát például a
``sudo gedit`` forma kerülendő.

Ha fájlokat kell másolgatni a könyvtárstruktúra különböző helyeire, akkor azt
konzolon, a megfelelően paraméterezett ``cp`` parancs segítségével tedd, hogy a
felhasználónak csak be kelljen másolnia a megfelelő sorokat a konzolba.

Ha mellékelsz képeket, 320 pixel szélességig normál méretben, e felett
nézőképként (hivatkozással a teljes méretű képre) helyezd el. Ha ez lehetséges,
a nézőkép ne csak egyszerűen egy átméretezett kép legyen, hanem inkább
kivágással emeld ki a fontos részt.

A képernyőképeket *PNG*, a fotókat *JPEG* formátumban töltsd fel.

Figyelj a licencekre és a jogszerűségre! Jelöld a felhasznált forrásokat, és
ha más dokumentációjából használsz fel részleteket, akkor azt tedd jogszerűen:
például a `GNU-FDL (Free Documentation License)`_ és a `CC-by-sa licenc`_ nem
kompatibilis egymással. Vagyis ha az útmutatódban szerepelnek GNU-FDL
alatt kiadott részletek, akkor az egész dokumentumot GNU-FDL licenc hatálya alá
kell helyezni.

Alapesetben minden, az oldalra beküldött dokumentáció a Creative Commons
`Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc`_ alá kerül. Kérlek jelezd,
ha ez valamilyen okból (például mert a felhasznált anyagok ezt nem teszik
lehetővé) nem felel meg - és nevezd meg a dokumentum felhasználási feltételeit.

Az írásod úgy tudod a felhasználók számára is elérhetővé tenni, ha felveszed
az index.rst fájlba. Figyelj oda, hogy a megfelelő szekcióba tedd, és igyekezz
úgy elhelyezni a sorban, hogy a felhasználók számára a legáttekinthetőbb legyen.

Ha bizonytalan vagy valamivel kapcsolatban (például hogy miről írj, milyen
megoldási utat válassz, hova helyezd el a dokumentumot) akkor kérdezz bátran a
levelezőlistán - végül is ezért van.

A dokumentum feltöltésével nem ért véget véglegesen a munka. Kövesd nyomon az
esetleges visszajelzéseket, hátha javítani kell rajta, vagy ki kell egészíteni,
és egy új Ubuntu kiadás megjelenésekor aktualizáld, ha szükséges. Ha már nem
szeretnéd karban tartani a dokumentumot, kérlek jelezd ezt az
`ubuntu-hu levelezési listán`_, hogy más át tudja venni tőled.

Mire figyelj a formázásnál
--------------------------
Egy sorba legfeljebb 80 karaktert írj. Ezt legegyszerűbben úgy tudod
ellenőrizni, ha például Geditben bekapcsolod a jobb oldali margót. Nyugodtan
használhatod a sortöréseket akár mondat közepén is, a renderelt oldalon ez nem
fog látszódni. Természetesen a linkeket, felsorolásokat és egyéb hosszú
egységeket nem kell megtörni.

Használd tudatosan és következetesen az alcímeket, hogy az egyes részek
könnyen követhetőek, az útmutató pedig áttekinthető legyen. A főcímet
egyenlőségjellel (=) húzd alá, az alcímeket kötőjellel (-).

A menüpontokat mindig dupla csillaggal jelöld, így a weboldalon \**bold**
karakterekkel fognak megjelenni. Például: \**Rendszer → Segítség és \támogatás**

Ha egy csomagról írsz, amit telepíteni kell, akkor annak a nevét tedd
\*csillagok* közé. Például: \*python-docutils* csomag.

A konzolparancsokat az alábbi módon jelezd:

\``sudo aptitude install \python-docutils``

Egy kép néha többet mond ezer szónál - ezért természetesen képekkel is gazdagon
illusztráld a mondandód. Persze ne feledkezz meg azokról sem, akik látási
nehézségekkel küzdenek. Számukra mindig töltsd ki informatívan az alt taget:

| \.. image:: img/reference-doc/reference-shot_tn.png
|	:target: img/reference-doc/reference-shot.png
|	:alt: Egy referencia képernyőkép az Ubunturól

A szövegben szereplő belső hivatkozások a dokumentum végén legyenek
összegyűjtve, ezzel is áttekinthetőbbé téve. A hivatkozást úgy tudod jelölni,
ha a szó végére egy alsó vonást teszel. Például: ubuntu.hu\_

Ha több szavas linket szeretnél, tedd egy-egy balra dőlő aposztróf közé,
valahogy így: \`Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc\`_

Azt, hogy egy-egy link milyen külső oldalra mutasson, a szöveg végén tudod
megadni. Például a fentebb említett ubuntu.hu link esetében ez így néz
ki: \``.. \_ubuntu.hu: \http://ubuntu.hu``

A `Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc` link esetében pedig a
következőképpen: \``.. \_Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc: \http://creativecommons.org/licenses/by-sa/2.5/hu/``

A dokumentáción belüli hivatkozásokat relatív módon, de a gyökérig visszalépve
határozzuk meg, az alábbi példának megfelelően:
\``.. \_Ubuntu telepítése: \../../main/install/install-live.html``

Vagyis minden esetben a ``../../`` sorral kezdjük (ezzel gyakorlatilag
visszalépünk két szintet, a branch gyökerébe), majd innen határozzuk meg az
elérési utat: ``main/install/install-live.html``. Mindig ezt a módszert
kövessük, még akkor is, ha egy könyvtárban található a dokumentumunk azzal,
amire hivatkozni szeretnénk, mert így később ha áthelyezzük az útmutatót, a
hivatkozás ugyanúgy működni fog, és a "../../" string keresésével később
könnyedén megtalálhatók a dokumentumon belüli belső hivatkozások. A fájlnév
természetesen mindig ugyanaz lesz, mint az rst fájl neve, a kiterjesztés
pedig .html lesz.

Természetesen használhatsz felsorolást is. A felsorolás lehet egyszerűen
pontokba szedve:

| - Ubuntu
| - Kubuntu
| - Xubuntu

Ezt akkor alkalmazd, ha egyszerűen csak fel szeretnél sorolni egymás mellé
rendelt elemeket. Előfordulhat azonban az is, hogy egymást követő lépéseket
szeretnél leírni. Ilyenkor sorszámozz:

| 1. Töltsd le és telepítsd a *python-docutils* csomagot
| 2. Írd meg az rst fájlt
| 3. Konvertáld át az rst-t html-be a teszteléshez
| 4. Töltsd fel a bazaar-ba az elkészült doksit

A reStructuredText formátum szigorúan veszi a behúzásokat, sortöréseket, üres
sorokat. Ezekre figyelj oda, mert emiatt is hibásan jelenhet meg a dokumentum.

Mielőtt feltöltenéd a módosított dokumentációt, teszteld le, hogy nincs-e
benne hiba. Erre az ``rst2html`` nevű eszközt használhatod, ami a
*python-docutils* csomag része. Ezt mindenképpen telepítsd fel:
``sudo aptitude install python-docutils``

Generáld le az rst fájlból a html fájlt:
``rst2html doksi.rst doksi.html``

Ha valamilyen formális hibát követtél el, erről hibaüzenet tájékoztat. A kész
dokumentumot egy webböngészőben tudod leellenőrizni. Figyelj arra, hogy a
html állományokat ne töltsd fel a branchbe. Ezt legegyszerűbben úgy teheted
meg, ha a saját mappádban a *.bazaar* könyvtárban található *ignore* fájlba
felveszed a html-t:
``*.html``
``*.htm``  

A verziókövető rendszer használata
----------------------------------
Telepítsd fel a bazaar verziókövető rendszert, ha még nem tetted meg korábban:
``sudo aptitude install bzr``

Ha grafikus eszközt is szeretnénk, telepítsd a *bzr-gtk* csomagot is:
``sudo aptitude install bzr-gtk``

Ezután hozd létre konzolban a felhasználót:
``bzr whoami "Példa Péter <pelda.peter@gmail.com>"``

Majd ellenőrizd le:
``bzr whoami``

Regisztrálj a Launchpadon, ha még korábban ezt nem tetted meg. A Launchpad_ a
Canonical koordinációs oldala, ami abban nyújt segítséget, hogy a szabad
szoftveres projektek aktivistái együtt tudjanak működni. Ha szeretnél részt
venni a dokumentációs csapat munkájában, kérd felvételed az ubuntu-hu-doc,
vagyis a Magyar Ubuntu Közösség dokumentációs csoportjába.

Ezután hozz létre egy ssh publikus kulcsot magadnak (ha még nem lenne), és
töltsd fel a Launchpadra. A kulcsot az **Alkalmazások → Kellékek → Jelszavak
és titkosítási kulcsok** alkalmazással tudod legegyszerűbben elkészíteni.
Itt válasszuk a **Fájl → Új** menüpontot. Ezen belül az válaszd az
**SSH kulcs** pontot. Add meg a kulcsleírást, majd kattints a **Csak
létrehozás** gombra. Add meg a jelmondatot, ami a kulcsodat védeni fogja.

Ezzel létrejön a kulcs a saját mappádban a .ssh alatt. Ez két fájlból áll:
az *id_rsa* a privát kulcs, az *id_rsa.pub* pedig a publikus kulcs. Ezután
töltsd fel a **publikus kulcsod** (*id_rsa.pub*) a launchpadra:
`https://launchpad.net/people/+me/+editsshkeys
<https://launchpad.net/people/+me/+editsshkeys>`_

Másold be a publikus kulcsod (az *id_rsa.pub* fájl tartalmát) a szövegdobozba
és klikkelj az **Import public key** gombra. Így már le tudod tölteni a
launchpadról a projektet a saját gépedre. Elsőként a gyakorló branchet töltsd
le: ez nem kerül ki a weboldalra, így nyugodtan tudsz rajta gyakorolni,
kísérletezni. Hozz létre egy könyvtárat, ahol a projektet szeretnéd tárolni,
majd tükrözd le:

``bzr checkout bzr+ssh://launchpadazonosító@bazaar.launchpad.net/~ubuntu-hu-doc/ubuntu-hu-doc/rookie``

Ezt követően máris megtalálhatod a gépeden a projekt fájljait, és munkához
láthatsz. Ha már korábban letükrözted a projektet, akkor mielőtt munkához
látnál, mindenképpen aktualizáld. Ehhez lépj az adott branchet tartalmazó könyvtárba
és ott add ki az alábbi parancsot: 

``bzr update``

Ha elvégezted a változatásaidat, és eközben új fájlok keletkeztek, add hozzá
ezeket a projekthez:

``bzr add <fájlnév>``

Majd commitolj:

``bzr commit -m "változtatások összefoglalása"``

Ez utóbbi két parancs is azt feltételezi, hogy az adott branch könyvtárában tartózkodsz.
A "változtatások összefoglalása" pedig néhány szavas leírása annak, amit tettél:
"link frissítése" vagy "gépelési hibák javítása" stb.
Ezzel fel is kerülnek a Launchpadra a változtatások. A rendszer minden óra 50 perckor
frissít és egészkor kerülnek ki láthatóan a változások. Figyelj
oda arra, hogy ha ilyenkor bent marad egy hiba, akkor azt csak egy óra múlva, a
következő szinkronizálással lehet javítani. 

Hogyan épül fel a könyvtárstruktúra
-----------------------------------
Az egyes kiadásokhoz készült útmutatók külön-külön branchben találhatók. A
branchek neve a kiadások kódnevére utal, vagyis az Ubuntu 8.04-hez
(Hardy Heron) készült dokumentációk egy *hardy*, az Ubuntu 8.10-hez
(Intrepid Ibex) készültek egy *intrepid*, az Ubuntu 9.04-hez
(Jaunty Jackalope) készültek egy *jaunty*, míg az Ubuntu 9.10-hez (Karmic Koala)
egy *karmic* nevű könyvtárban kapnak helyet.

A könyvtárakon belül két alkönyvtár található: *main* és *universe*

A *main* könyvtárban találhatók azok az útmutatók, amelyeket folyamatosan
karban tart a dokumentációs csoport, és kiadásról kiadásra aktualizál.

A *universe* könyvtárban találhatók azok az útmutatók, amelyeket egyszer
alaposan átnézett és kijavított a dokumentációs csoport, azonban nincs
kapacitása kiadásról kiadásra ellenőrizni és aktualizálni. Ezek frissítése
a rendelkező idő és kapacitás függvényében történik.

A dokumentumokhoz tartozó rst állományok ezen két könyvtár valamelyikében kapnak
helyet. Például: *main/install.rst*

A dokumentumhoz tartozó fotók és képernyőképek egy *img/dokumentum* alkönyvtárba
kerülnek, például: *main/img/install/install-live-hardy.png*

Figyelj arra, hogy a fájlnevek rövidek, tömörek és egyértelműek legyenek.

Az egyes kiadások dokumentációját tartalmazó branchek mellett van még egy,
rookie nevet viselő is: ez nem kerül ki a weboldalra, és kifejezetten a
gyakorlást, próbálkozást szolgálja. Amikor először ismerkedsz a verziókövető
rendszer és az rst működésével, ezen gyakorolj, hogy ha esetlegesen elrontanál
valamit, az ne érintse a nyilvános dokumentációt.

Hibák jelentése és követése
---------------------------
Természetesen, mint mindenben, így a közösségi dokumentációban is lehetnek
hibák. Ezek bejelentésére, koordinálására szintén a Launchpad_ szolgál. A
projekt hibabejelentő oldala a `https://bugs.launchpad.net/ubuntu-hu-doc
<https://bugs.launchpad.net/ubuntu-hu-doc>`_ címen érhető el. 

A dokumentációs csoport egyik legfontosabb feladata a dokumentációk létrehozása
mellett a hibák nyomon követése és javítása. Ebben a legfontosabb segítség a
Launchpad. A dokumentációs csoport tagjai itt tudják nyomon követni, hogy milyen
ismert hibák vannak az útmutatókban, és ennek segítségével tudják javítani.

Az új hibákat ezen az oldalon találod:
`https://bugs.launchpad.net/ubuntu-hu-doc/+bugs?search=Search&field.status=New
<https://bugs.launchpad.net/ubuntu-hu-doc/+bugs?search=Search&field.status=New>`_

Ha egy hiba javítását szeretnéd elvállalni, azt az **Assigned to** legördülő
menüponttal tudod megtenni: az *Assigned to* pont alatt válaszd a *Me* opciót,
így mindenki láthatja, hogy te foglalkozol vele.

Az **Importance** pont alatt tudod megadni a hiba fontosságát: Ennek különösen
akkor van nagy jelentősége, amikor egy új kiadás dokumentációja készül, hiszen
ilyenkor jelentősen megszaporodnak a bugreportok.

A **Status** pont alatt tudod megadni a bug helyzetét. A *New* azt jelenti, hogy
új hibáról van szó, az *Incomplete* azt, hogy a hibajelentés hiányos, az
*Invalid* azt, hogy nem megfelelő vagy nem értelmezhető, a *Won't Fix* azt,
hogy a hibát valamilyen okból nem fogjuk javítani (például azért, mert nem is
hiba). A *Confirmed* azt, hogy a hiba megerősített, a *Triaged* azt, hogy a
hiba reprodukálható (ez dokumentáció esetében nem szükséges), az *In Progress*
azt, hogy a hiba javítás alatt áll, a *Fix Committed* azt jelenti, hogy a
javítás már a bazaarban van, míg a *Fix Released* azt jelenti, hogy a javítás
kikerült az oldalra.

Fontos, hogy ha javítottál egy bejelentett hibát, akkor azt itt is jelezd, és
zárd le a nyitott bugreportot.

Erről az útmutatóról
--------------------
Ez az útmutató jelenleg még készítés alatt áll. Még hiányozhatnak belőle olyan
fontos dolgok, amelyek a hatékony és eredményes munka előfeltételei lehetnek.
Éppen ezért, ha bármiben bizonytalan lennél, akkor kérdezz bátran. A kérdéseid
és a menet közben szerzett tapasztalatok függvényében bővül folyamatosan majd
ez az útmutató is.

.. _Launchpad: http://launchpad.net
.. _ubuntu.hu: http://ubuntu.hu
.. _Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc: http://creativecommons.org/licenses/by-sa/2.5/hu/
.. _GNU-FDL (Free Documentation License): http://www.gnu.org/licenses/fdl.html
.. _CC-by-sa licenc: http://creativecommons.org/licenses/by-sa/3.0/
.. _ubuntu-hu levelezési listán: https://lists.ubuntu.com/mailman/listinfo/ubuntu-hu