← Back to branch summary

~ubuntu-hu-doc/ubuntu-hu-doc/rookie

« back to all changes in this revision

Viewing changes to main/community/reference-doc.rst

  • Committer: Kiszel Kristóf
  • Date: 2009-08-12 22:06:47 UTC
  • Revision ID: ulysses.mik@gmail.com-20090812220647-34vn4q5fadnfmvxe
rookie kicsit rendezve, tisztítva

Show diffs side-by-side

added added

removed removed

Lines of Context:
main/community/reference-doc.rst
 
1
Referencia dokumentáció
 
2
=======================
 
3
 
 
4
Miről szól a referencia dokumentáció
 
5
------------------------------------
 
6
Ezen útmutató segítségével megtanulhatod, hogy hogyan vehetsz részt az ubuntu
 
7
dokumentációs csoport munkájában, hogyan kell kinéznie egy ubuntu.hu_ oldalon
 
8
megjelenő hivatalos dokumentációnak, valamint hogy hogyan használhatod a bazaar
 
9
verziókezelő rendszert a munka során. A dokumentum megmutatja, hogyan írhatsz
 
10
hasonlóan egységes útmutatókat, mint amilyeneket a **Rendszer -> Segítség és
 
11
támogatás** menüpontban találhatsz, és hogyan tarthatod ezeket karban, a
 
12
többiekkel együttműködve.
 
13
 
 
14
Hogyan kezdj bele
 
15
-----------------
 
16
Telepítsd fel a *python-docutils*, a *bzr* és a *bzr-gtk* csomagokat:
 
17
 
 
18
``sudo aptitude install python-docutils bzr bzr-gtk``
 
19
 
 
20
Hogyan írj dokumentációt
 
21
------------------------
 
22
Ebben a dokumentumban összegyűjtöttük a legfontosabb irányelveket, ajánlásokat
 
23
és tudnivalókat a dokumentációkat, útmutatókat készítők számára. Kérjük, ezeket
 
24
tartsd szem előtt, amikor dolgozol:
 
25
 
 
26
Törekedj az érhető fogalmazása, és az egyértelmű terminológiára.
 
27
 
 
28
Figyelj oda a helyesírásra, nyelvhelyességre és az áttekinthető tördelésre.
 
29
 
 
30
Ahol lehet, használj magyar kifejezéseket - de nem mindenáron: ha a
 
31
gyakorlatban az angol kifejezés terjedt el (például kernel) használd nyugodtan
 
32
azt.
 
33
 
 
34
Mindig a magyar felhasználói felület kifejezéseid használd - kivéve, ahol ez
 
35
értelemszerűen nem lehetséges (mert az adott alkalmazás nem érhető el magyar
 
36
nyelven), vagy értelmetlen lenne (például arról írsz, hogy hogyan lehet egy
 
37
angol rendszerre a magyar nyelvi támogatást telepíteni utólag).
 
38
 
 
39
Grafikus felületen a **synaptic**, konzolon az **aptitude** a preferált
 
40
csomagkezelő, így a leírásokban is ezek szerepeljenek.
 
41
 
 
42
Az alapértelmezett disztribúció az Ubuntu. Vagyis hacsak nem kifejezetten
 
43
Kubuntu vagy Xubuntu specifikus a téma, akkor mindig az Ubuntu-t vedd alapul,
 
44
és erről készüljenek a képernyőképek is.
 
45
 
 
46
Grafikus alkalmazásokat grafikus csomagkezelővel (synaptic), konzolos
 
47
alkalmazásokat konzolos csomagkezelővel (aptitude) telepítsd.
 
48
 
 
49
Külső forrásból származó csomagokat csak akkor használj, ha ez *tényleg*
 
50
elkerülhetetlen (például ABEVJava).
 
51
 
 
52
Konzolos alkalmazásokat a ``sudo``, grafikus alkalmazásokat a ``gksu``
 
53
(Ubuntu és Xubuntu esetében) vagy a ``kdesudo`` (Kubuntu esetében) paranccsal
 
54
indítsd, ha rendszergazdai jogosultságot igényelnek. Vagyis ``sudo nano ...``
 
55
vagy ``gksu gedit ...``, esetleg ``kdesudo kate ...`` - tehát például a
 
56
``sudo gedit`` forma kerülendő.
 
57
 
 
58
Ha fájlokat kell másolgatni a könyvtárstruktúra különböző helyeire, akkor azt
 
59
konzolon, a megfelelően paraméterezett ``cp`` parancs segítségével tedd, hogy a
 
60
felhasználónak csak be kelljen másolnia a megfelelő sorokat a konzolba.
 
61
 
 
62
Ha mellékelsz képeket, 320 pixel szélességig normál méretben, e felett
 
63
nézőképként (hivatkozással a teljes méretű képre) helyezd el. Ha ez lehetséges,
 
64
a nézőkép ne csak egyszerűen egy átméretezett kép legyen, hanem inkább
 
65
kivágással emeld ki a fontos részt.
 
66
 
 
67
A képernyőképeket *PNG*, a fotókat *JPEG* formátumban töltsd fel.
 
68
 
 
69
Figyelj a licencekre és a jogszerűségre! Jelöld a felhasznált forrásokat, és
 
70
ha más dokumentációjából használsz fel részleteket, akkor azt tedd jogszerűen:
 
71
például a `GNU-FDL (Free Documentation License)`_ és a `CC-by-sa licenc`_ nem
 
72
kompatibilis egymással. Vagyis ha az útmutatódban szerepelnek GNU-FDL
 
73
alatt kiadott részletek, akkor az egész dokumentumot GNU-FDL licenc hatálya alá
 
74
kell helyeni.
 
75
 
 
76
Alapesetben minden, az oldalra beküldött dokumentáció a Creative Commons
 
77
`Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc`_ alá kerül. Kérlek jelezd,
 
78
ha ez valamilyen okból (például mert a felhasznált anyagok ezt nem teszik
 
79
lehetővé) nem felel meg - és nevezd meg a dokumentum felhasználási feltételeit.
 
80
 
 
81
Az írásod úgy tudod a felhasználók számára is elérhetővé tenni, ha felveszed
 
82
az index.rst fájlba. Figyelj oda, hogy a megfelelő szekcióba tedd, és igyekezz
 
83
úgy elhelyezni a sorban, hogy a felhasználók számára a legáttekinthetőbb legyen.
 
84
 
 
85
Ha bizonytalan vagy valamivel kapcsolatban (például hogy miről írj, milyen
 
86
megoldási utat válassz, hova helyezd el a dokumentumot) akkor kérdezz bátran a
 
87
levelezőlistán - végülis ezért van.
 
88
 
 
89
A dokumentum feltöltésével nem ért véget véglegesen a munka. Kövesd nyomon az
 
90
esetleges visszajelzéseket, hátha javítani kell rajta, vagy ki kell egészíteni,
 
91
és egy új Ubuntu kiadás megjelenésekor aktualizáld, ha szükséges. Ha már nem
 
92
szeretnéd karban tartani a dokumentumot, kérlek jelezd ezt az
 
93
`ubuntu-hu levelezési listán`_, hogy más át tudja venni tőled.
 
94
 
 
95
Mire figyelj a formázásnál
 
96
--------------------------
 
97
Egy sorba legfeljebb 80 karaktert írj. Ezt legegyszerűbben úgy tudod
 
98
ellenőrizni, ha például Geditben bekapcsolod a jobb oldali margót. Nyugodtan
 
99
használhatod a sortöréseket akár mondat közepén is, a renderelt oldalon ez nem
 
100
fog látszódni. Természetesen a linkeket, felsorolásokat és egyéb hosszú
 
101
egységeket nem kell megtörni.
 
102
 
 
103
Használd tudatosan és következetesen az alcímeket, hogy az egyes részek
 
104
könnyen követhetőek, az útmutató pedig áttekinthető legyen. A főcímet
 
105
egyenlőségjellel (=) húzd alá, az alcímeket kötőjellel (-).
 
106
 
 
107
A menüpontokat mindig dupla csillaggal jelöld, így a weboldalon **bold**
 
108
karakterekkel fognak megjelenni. Például: **Rendszer -> Segítség és támogatás**
 
109
 
 
110
Ha egy csomagról írsz, amit telepíteni kell, akkor annak a nevét tedd
 
111
*csillagok* közzé - például *python-docutils* csomag.
 
112
 
 
113
A konzolparancsokat az alábbi módon jelezd:
 
114
 
 
115
``sudo aptitude install python-docutils``
 
116
 
 
117
Egy kép néha többet mond ezer szónál - ezért természetesen képekkel is gazdagon
 
118
illusztráld a mondandód. Persze ne feledkezz meg azokról sem, akik látási
 
119
nehézségekkel küzdenek. Számukra mindig töltsd ki informatívan az alt taget:
 
120
 
 
121
.. image:: img/reference-doc/reference-shot_tn.png
 
122
        :target: img/reference-doc/reference-shot.png
 
123
        :alt: Egy referencia képernyőkép az Ubunturól
 
124
 
 
125
A szövegben szereplő belső hivatkozások a dokumentum végén legyenek
 
126
összegyűjtve, ezzel is áttekinthetőbbé téve. A hivatkozást úgy tudod jelölni,
 
127
ha a szó végére egy alsóvonást teszel. Például: ubuntu.hu_
 
128
 
 
129
Ha több szavas linkeket szeretnél, tedd egy-egy balra dőlő aposztróf közzé,
 
130
valahogy így: `Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc`_
 
131
 
 
132
Azt, hogy egy-egy link milyen külső oldalra mutasson, a szöveg végén tudod
 
133
megadni. Például a fentebb említett ubuntu.hu link esetében ez így néz
 
134
ki: ``.. _ubuntu.hu: http://ubuntu.hu``
 
135
 
 
136
A `Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc` link esetében pedig a
 
137
következő képpen: ``.. _Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc: http://creativecommons.org/licenses/by-sa/2.5/hu/``
 
138
 
 
139
A dokumentáción belüli hivatkozásokat relatív módon, de a gyökérig visszalépve
 
140
határozzuk meg, az alábbi példának megfelelően:
 
141
``.. _Ubuntu telepítése: ../../main/install/install-live.html``
 
142
Vagyis minden esetben a ``../../`` sorral kezdjük (ezzel gyakorlatilag
 
143
visszalépünk két szintet, a branch gyökerébe), majd innen határozzuk meg az
 
144
elérési utat ``main/install/install-live.html``. Minden esetben ezt a módszert
 
145
kövessük, még akkor is, ha egy könyvtárban található a dokumentumunk azzal,
 
146
amire hivatkozni szeretnénk, mert így később ha áthelyezzük az útmutatót, a
 
147
hivatkozás ugyanúgy működni fog, és a "../../" string keresésével később
 
148
könnyedén megtalálhatók a dokumentumon belüli belső hivatkozások. A fájlnév
 
149
természetesen mindig ugyanaz lesz, mint az rst fájl neve, a kiterjesztés
 
150
pedig .html lesz.
 
151
 
 
152
Természetesen használhatsz felsorolásokat is. A felsorolás lehet egyszerűen
 
153
pontokba szedve:
 
154
 
 
155
- Ubuntu
 
156
- Kubuntu
 
157
- Xubuntu
 
158
 
 
159
Ezt akkor alkalmazd, ha egyszerűen csak fel szeretnénk sorolni egymás mellé
 
160
rendelt elemeket. Előfordulhat az is azonban, hogy egymás követő lépéseket
 
161
szeretnél leírni. Ilyenkor sorszámozz:
 
162
 
 
163
1. Töltsd le és telepítsd a *python-docutils* csomagot
 
164
2. Írd meg az rst fájlt
 
165
3. Konvertáld át az rst-t html-be a teszteléshez
 
166
4. Töltsd fel a bazaar-ba az elkészült doksit
 
167
 
 
168
A reStructuredText formátum szigorúan veszi a behúzásokat, sortöréseket, üres
 
169
sorokat. Ezekre figyelj oda, mert emiatt is hibásan jelenhet meg a dokumentum.
 
170
 
 
171
Mielőtt feltöltenénk a módosított dokumentációt, teszteld le, hogy nincs-e
 
172
benne hiba. Erre az ``rst2html`` nevű eszközt használhatodk, ami a
 
173
*python-docutils* csomag része. Ezt mindenképpen telepítsd fel:
 
174
``sudo aptitude install python-docutils``
 
175
 
 
176
Generáld le az rst fájlból a html fájlt:
 
177
``rst2html doksi.rst doksi.html``
 
178
 
 
179
Ha valamilyen formális hibát követtél el, erről hibaüzenet tájékoztat. A kész
 
180
dokumentumot egy webböngészőben tudod leellenőrizni. Figyelj arra, hogy a
 
181
html állományokat ne töltsd fel a branchbe. Ezt legegyszerűbben úgy teheted
 
182
meg, ha a saját mappádban a *.bazaar* könyvtárban található *ignore* fájlba
 
183
felveszed a html-t:
 
184
``*.html``
 
185
``*.htm``  
 
186
 
 
187
A verziókövető rendszer használata
 
188
----------------------------------
 
189
Telepítsd fel a bazaar verziókövető rendszert, ha még nem tetted meg korábban:
 
190
``sudo aptitude install bzr``
 
191
 
 
192
Ha grafikus eszközt is szeretnénk, telepítsd a *bzr-gtk* csomagot is:
 
193
``sudo aptitude install bzr-gtk``
 
194
 
 
195
Ezután hozd létre konzolban a felhasználót:
 
196
``bzr whoami "Példa Péter <pelda.peter@gmail.com>"``
 
197
 
 
198
Majd ellenőrizd le:
 
199
``bzr whoami``
 
200
 
 
201
Regisztrálj a Launchpadon, ha még korábban ezt nem tetted meg. A Launchpad_ a
 
202
Canonical koordinációs oldala, ami abban nyújt segítséget, hogy a szabad
 
203
szoftveres projektek aktivistái együtt tudjanak működni. Ha szeretnél részt
 
204
venni a dokumentációs csapat munkájában, kérd felvételed az ubuntu-hu-doc,
 
205
vagyis a Magyar Ubuntu Közösség dokumentációs csoportjába.
 
206
 
 
207
Ezután hozz létre egy ssh publikus kulcsot magadnak (ha még nem lenne), és
 
208
töltsd fel a Launchpadra. A kulcsot az **Alkalmazások -> Kellékek -> Jelszavak
 
209
és titkosítási kulcsok** alkalmazással tudod legegyszerűbben elkészíteni.
 
210
Itt válasszuk a **Fájl -> Új** menüpontot. Ezen belül az válaszd az
 
211
**SSH kulcs** pontot. Add meg a kulcsleírást, majd kattints a **Csak
 
212
létrehozás** gombra. Add meg a jelmondatot, ami a kulcsodat védeni fogja.
 
213
 
 
214
Ezzel létrejön a kulcs a saját mappádban a .ssh alatt. Ez két fájlból áll:
 
215
az *id_rsa* a privát kulcs, az *id_rsa.pub* pedig a publikus kulcs. Ezután
 
216
töltsd fel a **publikus kulcsod** (*id_rsa.pub*) a launchpadra:
 
217
`https://launchpad.net/people/+me/+editsshkeys
 
218
<https://launchpad.net/people/+me/+editsshkeys>`_
 
219
 
 
220
Másold be a publikus kulcsod (az *id_rsa.pub* fájl tartalmát) a szövegdobozba
 
221
és klikkelj az **Import public key** gombra. Így már le tudod tölteni a
 
222
launchpadról a projektet a saját gépünkre. Elsőként a gyakorló branchet töltsd
 
223
le: ez nem kerül ki a weboldalra, így nyugodtan tudsz rajta gyakorolni,
 
224
kísérletezni. Hozz létre egy könyvtárat, ahol a projektet szeretnénk tárolni,
 
225
majd tükrözd le:
 
226
 
 
227
``bzr checkout bzr+ssh://launchpadazonosító@bazaar.launchpad.net/~ubuntu-hu-doc/ubuntu-hu-doc/rookie``
 
228
 
 
229
Ezt követően máris megtalálhatod a gépeden a projekt fájljait, és munkához
 
230
láthatsz. Ha már korábban letükrözted a projektet, akkor mielőtt munkához
 
231
látnál, mindenképpen aktualizáld:
 
232
 
 
233
``bzr update``
 
234
 
 
235
Ha elvégezted a változatásaidat, és eközben új fájlok keletkeztek, add hozzá
 
236
ezeket a projekthez:
 
237
 
 
238
``bzr add <fájlnév>``
 
239
 
 
240
Majd commitolj:
 
241
 
 
242
``bzr commit -m "változtatások összefoglalása"``
 
243
 
 
244
Ezzel fel is kerülnek a Launchpadra a változtatások. Az ubuntu.hu weboldal pedig
 
245
minden nap egyszer, pontban éjfélkor szinkronizálja a változásokat a
 
246
Launchpadról. Így mindaz, amit napközben alkotsz, éjszaka fog kikerülni. Figyelj
 
247
oda arra, hogy ha ilyenkor bentmarad egy hiba, akkor azt csak 24 óra múlva, a
 
248
következő szinkronizálással lehet javítani. 
 
249
 
 
250
Hogyan épül fel a könyvtárstruktúra
 
251
-----------------------------------
 
252
Az egyes kiadásokhoz készült útmutatók külön-külön branchben találhatók. A
 
253
branchek neve a kiadások kódnevére utal, vagyis az Ubuntu 8.04-eshez (Hardy Heron)
 
254
készült dokumentációk egy *hardy*, míg az Ubuntu 8.10-eshez (Intrepid Ibex)
 
255
készültek egy *intrepid* nevű könyvtárban kapnak helyet. A könyvtárakon belül
 
256
két alkönyvtár található: *main* és *universe*
 
257
 
 
258
A *main* könyvtárban találhatók azok az útmutatók, amelyeket folyamatosan
 
259
karban tart a dokumentációs csoport, és kiadásról kiadásra aktualizál.
 
260
 
 
261
A *universe* könyvtárban találhatók azok az útmutatók, amelyeket egyszer
 
262
alaposan átnézett és kijavított a dokumentációs csoport, azonban nincs
 
263
kapacitása kiadásról kiadásra ellenőrizni és aktualizálni. Ezek frissítése
 
264
a rendelkező idő és kapacitás függvényében történik.
 
265
 
 
266
A dokumentumokhoz tartozó rst állományok ezen két könyvtár valamelyikében kapnak
 
267
helyet. Például: *main/install.rst*
 
268
 
 
269
A dokumentumhoz tartozó fotók és képernyőképek egy *img/dokumentum* alkönyvtárba
 
270
kerülnek, például: *main/img/install/install-live-hardy.png*
 
271
 
 
272
Figyelj arra, hogy a fájlnevek rövidek, tömörek és egyértelműek legyenek.
 
273
 
 
274
Az egyes kiadások dokumentációját tartalmazó branchek mellett van még egy,
 
275
rookie nevet viselő is: ez nem kerül ki a weboldalra, és kifejezetten a
 
276
gyakorlást, próbálkozást szolgálja. Amikor először ismerkedsz a verziókövető
 
277
rendszer és az rst működésével, ezen gyakorolj, hogy ha esetlegesen elrontanál
 
278
valamit, az ne érintse a nyilvános dokumentációt.
 
279
 
 
280
Hibák jelentése és követése
 
281
---------------------------
 
282
Természetesen, mint mindenben, így a közösségi dokumentációban is lehetnek
 
283
hibák. Ezek bejelentésére, koordinálására szintén a Launchpad_ szolgál. A
 
284
projekt hibabejelentő oldala a `https://bugs.launchpad.net/ubuntu-hu-doc
 
285
<https://bugs.launchpad.net/ubuntu-hu-doc>`_ címen érhető el. 
 
286
 
 
287
A dokumentációs csoport egyik legfontosabb feladata a dokumentációk létrehozása
 
288
mellett a hibák nyomon követése és javítása. Ebben a legfontosabb segítség a
 
289
Launchpad. A dokumentációs csoport tagjai itt tudják nyomon követni, hogy milyen
 
290
ismert hibák vannak az útmutatókban, és ennek segítségével tudják javítani.
 
291
 
 
292
Az új hibákat ezen az oldalon találod:
 
293
`https://bugs.launchpad.net/ubuntu-hu-doc/+bugs?search=Search&field.status=New
 
294
<https://bugs.launchpad.net/ubuntu-hu-doc/+bugs?search=Search&field.status=New>`_
 
295
 
 
296
Ha egy hiba javítását szeretnéd elvállalni, azt az **Assigned to** legördülő
 
297
menüponttal tudod megtenni: az *Assigned to* pont alatt válaszd a *Me* opciót,
 
298
így mindenki láthatja, hogy te foglalkozol vele.
 
299
 
 
300
Az **Importance** pont alatt tudod megadni a hiba fontosságát: Ennek különösen
 
301
akkor van nagy jelentősége, amikor egy új kiadás dokumentációja készül, hiszen
 
302
ilyenkor jelentősen megszaporodnak a bugreportok.
 
303
 
 
304
A **Status** pont alatt tudod megadni a bug helyzetét. A *New* azt jelenti, hogy
 
305
új hibáról van szó, az *Incomplete* azt, hogy a hibajelentés hiányos, az
 
306
*Invalid* azt, hogy nem megfelelő vagy nem értelmezhető, a *Won't Fix* azt,
 
307
hogy a hibát valamilyen okból nem fogjuk javítani (például azért, mert nem is
 
308
hiba). A *Confirmed* azt, hogy a hiba megerősített, a *Triaged* azt, hogy a
 
309
hiba reprodukálható (ez dokumentáció esetében nem szükséges), az *In Progress*
 
310
azt, hogy a hiba javítás alatt áll, a *Fix Committed* azt jelenti, hogy a
 
311
javítás már a bazaarban van, míg a *Fix Released* azt jelenti, hogy a javítás
 
312
kikerült az oldalra.
 
313
 
 
314
Fontos, hogy ha javítottál egy bejelentett hibát, akkor azt itt is jelezd, és
 
315
zárd le a nyitott bugreportot.
 
316
 
 
317
Erről az útmutatóról
 
318
--------------------
 
319
Ez az útmutató jelenleg még készítés alatt áll. Még hiányozhatnak belőle olyan
 
320
fontos dolgok, amelyek a hatékony és eredményes munka előfeltételei lehetnek.
 
321
Éppen ezért, ha bármiben bizonytalan lennél, akkor kérdezz bátran. A kérdéseid
 
322
és a menet közben szerzett tapasztalatok függvényében bővül folyamatosan majd
 
323
ez az útmutató is.
 
324
 
 
325
.. _Launchpad: http://launchpad.net
 
326
.. _ubuntu.hu: http://ubuntu.hu
 
327
.. _Nevezd meg!-Így add tovább! 2.5 Magyarország Licenc: http://creativecommons.org/licenses/by-sa/2.5/hu/
 
328
.. _GNU-FDL (Free Documentation License): http://www.gnu.org/licenses/fdl.html
 
329
.. _CC-by-sa licenc: http://creativecommons.org/licenses/by-sa/3.0/
 
330
.. _ubuntu-hu levelezési listán: https://lists.ubuntu.com/mailman/listinfo/ubuntu-hu