« back to all changes in this revision
Viewing changes to resources/reference-doc.rst
- browse files at revision 55
- compare with another revision
- compare with revision 58
- download diff
- download tarball
- view history from revision 55
- 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
- files added:
- main/community
- main/community/img
- main/community/img/reference-doc
- universe/apps
- files removed:
- main/connection
- resources
- resources/img
- resources/img/reference-doc
- universe/server
- files modified:
- index.rst
added
removed
resources/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
Loggerhead is a web-based interface for Breezy
Version: 2.0.1