1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
|
<?xml version = '1.0' encoding = 'UTF-8'?>
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
<guide link="/doc/it/xml-guide.xml" >
<title>Gentoo Linux Documentation Guide</title>
<author title="Author" >
<mail link="drobbins@gentoo.org" >Daniel Robbins</mail>
</author>
<author title="Editor" >
<mail link="zhen@gentoo.org" >John P. Davis</mail>
</author>
<author title="Traduttore" >
<mail link="stefano.mazzone@tin.it" >Stefano Mazzone</mail>
</author>
<author title="Traduttore" >
Team Italiano
</author>
<abstract>Questa guida ti mostra come comporre documentazione web usando la nuova sintassi guide XML
di Gentoo. Questa sintassi è il formato ufficiale della documentazione Gentoo Linux, e questo
documento è stato creato usando XML guide. Questa guida presuppone una conoscenza di base di
XML e HTML.
.
</abstract>
<version>1.2</version>
<date>16 January 2002</date>
<chapter>
<title>Guide basics</title>
<section>
<title>Guide XML: obiettivi</title>
<body>
<p>La sintassi "guide XML" è leggera ma espressiva, così che è facile da
imparare, inoltre fornisce anche tutto ciò di cui hai bisogno per creare
documentazione per il web. Il numero dei tags è mantenuto al minimo
indispensabile. Questo rende facile trasformare i documenti in altri formati
come DocBook XML/SGML o vere e proprie pagine HTML. </p>
<p>L'obiettivo è di <e>creare</e> e <e>convertire</e> facilmente documenti guide XML.</p>
</body>
</section>
<section>
<title>Come convertire guide XML in HTML</title>
<body>
<p> Prima di dare uno sguardo alla sintassi stessa, è utile conoscere come
un documento XML è convertito in uno HTML. Per far questo, usiamo un
file speciale chiamato <path>guide.xsl</path>, insieme con un XSLT processing
tool (chiamato anche "engine"). Il file <path>guide.xsl</path> descrive
esattamente come convertire il contenuto di un documento sorgento XML
per creare un file destinazione HTML. Due popolari processori XSLT sono <c>sabcmd</c>
(incluso nel package <path>app-text/sablotron</path>) e <c>xsltproc</c>
(trovato nel package <path>dev-libs/libxslt</path>). Per esperienza, abbiamo
travato che <c>xsltproc</c> è qualitativamente migliore ed è inoltre un
processore XSLT ricco di features.
</p>
<p> Una volta che hai installato <c>xsltproc</c> o <c>sabcmd</c> , sei
pronto per convertire documenti XML in HTML. Sebbene, prima di fare questo,
è necessario comunque prelevare l'ultimo snapshot del nostro albero web.
</p>
<p>Il tarball gzipped del sito web può essere trovato
<uri link="http://www.gentoo.org/dyn/arch/xml-guide-latest.tar.gz" >qui</uri>.
</p>
<note>Puoi ora scaricare il set completo della documentazione Gentoo Linux per la tua
lingua, senza dover scaricare l'albero web completo. Puoi navigare in
<uri>http://www.gentoo.org/dyn/doc-snapshots</uri> per cercare i tarballs.
</note>
<p>Ora, estrai il tarball. Al suo interno, troverai una directory <path>htdocs</path>
. Cerca il file <path>htdocs/doc/<your lang>/gentoo-x86-install.xml</path>
(La nuova guida utente all'installazione). Questo sarà il nostro sorgente XML.
La via più facile per eseguire la conversione è di cambiare la directory e di
andare dove e situato il file
<path>guide.xsl</path> . Quindi, eseguire <c>xsltproc</c> come segue:
</p>
<pre caption="Transforming gentoo-x86-install.xml" >
# <c>cd gentoo-web/xsl</c>
# <c>xsltproc guide.xsl ../doc/<your lang>/gentoo-x86-install.xml > /tmp/install.html</c>
</pre>
<p> Se tutto è andato bene, dovresti avere una versione
web-ready del file
<path>gentoo-x86-install.xml</path> in <path>/tmp/install.html</path>. Per poter visualizzare
correttamente questo documento con un web browser, dovrai copiare alcuni
file da
<path>htdocs</path> a <path>/tmp</path>, come <path>css/main-new.css</path> e (per essere sicuri) l'intera directory <path>images</path>
.
</p>
</body>
</section>
</chapter>
<chapter>
<title>Guide XML</title>
<section>
<title>Struttura di base</title>
<body>
<p>Ora che sai come trasformare un documento XML, sei pronto per imparare
la sintassi "guide XML". Comincieremo con il tag d'inizio usato in un documento
"guide XML": </p>
<pre caption="The initial part of a guide XML document" >
<?xml version='1.0' encoding="UTF-8"?>
<guide link="relative_link_to_your_guide">
<title><i>Gentoo Linux Documentation Guide</i></title>
<author title="<i>Chief Architect</i>"><mail link="<i>drobbins@gentoo.org</i>">
<i>Daniel Robbins</i></mail>
</author>
<author title="<i>Editor</i>"><mail link="<i>thomasfl@gentoo.org</i>">
<i>Thomas Flavel</i></mail>
</author>
<abstract><i>This guide shows you how to compose web documentation using
our new lightweight Gentoo guide XML syntax. This syntax is the official
format for Gentoo Linux web documentation, and this document itself was created
using guide XML.</i> </abstract>
<version><i>1.0</i></version>
<date><i>29 Mar 2001</i></date>
</pre>
<impo>Se sei in procinto di committare documenti, è necessario leggere la
<uri link="http://www.gentoo.org/doc/it/doc-developer-guide.xml" >Gentoo Documentation Developer's Policy</uri>.
</impo>
<p>Nella prima linea, troviamo il tag che identifica questo come un documento
XML. Di seguito, è presente un tag
<c><guide></c> -- l'intero
documento è racchiuso all'interno di una coppia di tags <c><guide> </guide></c> .
C'è quindi un tag <c><title></c> , usato per definire il titolo dell'intero
documento.
</p>
<p>Arriviamo ai tags <c><author></c> , che contengono informazioni
relative ai vari autori del documento. Ogni tag <c><author></c> accetta un elemento opzionale <c>title=</c> , usato per specificare la relazione
tra l'autore e il documento (author, co-author, editor, etc.). In questo
caso particolare, il nominativo dell'autore è racchiuso in un altro tag
<c><mail></c> , usato per specificare un indirizzo email per questa
persona. Il tag <c><mail></c> è opzionale è puo essere omesso, inoltre
è richiesto non più di un elemento <c><author></c> per documento.
</p>
<p>Incontriamo, in seguito, i tags <c><abstract></c>, <c><version></c> e
<c><date></c> , usati per specificare rispettivamente: un riassunto del documento, il
numero di versione corrente, e la data della versione corrente (nel formato DD MMM YYYY).
Questa serie di tags dovrebbe apparire all'inizio del documento.
Ad eccezione dei tags
<c><title></c> e <c><mail></c>
, questi tags non dovrebbero apparire in nessun'altra parte, eccetto immediatamente dentro il tag
<c><guide></c> , e per coerenza è raccomandato (ma non
richiesto) che questi tags appaiano prima del contenuto del documento.
</p>
</body>
</section>
<section>
<title>Capitoli e sezioni</title>
<body>
<p>Una volta specificati i tags iniziali, sei pronto per iniziare ad aggiungere
elementi strutturali al documento. I documenti sono divisi in capitoli, e
ogni capitolo può avere una o più sezioni. Capitoli e sezioni hanno
sempre un titolo. Segue un capitolo d'esempio con una singola sezione,
composta da un paragrafo. Se aggiungi questo XML all'<uri link="#doc_pre2" >estratto
precedente</uri> e termini il tutto con <c></guide></c> , avrai un valido
(anche se minimo) documento:
</p>
<pre>
<chapter>
<title><i>This is my chapter</i></title>
<section>
<title><i>This is section one of my chapter</i></title>
<body>
<p><i>This is the actual text content of my section.</i></p>
</body>
</section>
</chapter>
</pre>
<p>Sopra, abbiamo inserito il titolo del capitolo,
aggiungendo un elemento <c><title></c>
figlio dell'elemento <c><chapter></c> . Quindi, abbiamo creato una sezione,
aggiungendo un elemento <c><section></c> . Se guardi all'interno dell'elemento
<c><section></c> , vedrai due elementi figli -- un
<c><title></c> ed un <c><body></c>. Mentre <c><title></c>
non è nuovo, lo è <c><body></c> -- che contiene l'attuale testo
all'interno di una data sezione. Daremo un'occhiata a quali tags sono
permessi all'interno dell'elemento <c><body></c>. </p>
<note>Un elemento <c><guide></c> può contenere più elementi
<c><chapter></c>, ed un elemento <c><chapter></c> può contenere
più elementi <c><section></c>. Tuttavia, un elemento <c><section></c>
può contenere solo un elemento <c><body></c>. </note>
</body>
</section>
<section>
<title>Un esempio di <body></title>
<body>
<p>
è ora tempo di imparare come arricchire il contenuto corrente. Ecco un esempio di codice XML per l'elemento <c><body></c>:
</p>
<pre>
<p>
Questo è un paragrafo. <path>/etc/passwd</path> è un file.
<uri>http://www.gentoo.org</uri> è il mio website preferito.
Se hai voglia digita <c>ls</c>. Voglio <e>davvero</e> andare a dormire.
</p>
<pre>
Questo è l'output.
# <i>questo è l'input dell'utente</i>
Rendi l' HTML/XML facile da leggere usando selective emphasis:
<foo><i>bar</i></foo>
<codenote>Ecco come inserire una nota in un blocco di codice</codenote>
</pre>
<note>Questa è una nota.</note>
<warn>Questo è un warning.</warn>
<impo>Questo è importante.</impo>
</pre>
<p>Ecco ora, come questo elemento <c><body></c> è disegnato:</p>
<p>
Questo è un paragrafo. <path>/etc/passwd</path> è un file.
<uri>http://www.gentoo.org</uri> è il mio website preferito.
Se hai voglia digita <c>ls</c>. Voglio <e>davvero</e> andare a dormire.
</p>
<pre>
Questo è l'output.
# <i>questo è l'input dell'utente</i>
Rendi l' HTML/XML facile da leggere usando selective emphasis:
<foo><i>bar</i></foo>
<codenote>Ecco come inserire una nota in un blocco di codice</codenote>
</pre>
<note>Questa è una nota.</note>
<warn>Questo è un warning.</warn>
<impo>Questo è importante.</impo>
</body>
</section>
<section>
<title>I tags <body></title>
<body>
<p> Abbiamo introdotto molti nuovi tags nella sezione precedente -- ecco cosa devi
conoscere. I tags <c><p></c> (paragrafo), <c><pre></c> (blocco
di codice), <c><note></c>, <c><warn></c> (warning) e
<c><impo></c> (importante), posssono tutti contenere una o più linee di testo.
Oltre l'elemento <c><table></c> (Che vedremo tra poco),
ci sono tags che dovrebbero apparire immediatamente all'interno
dell'elemento <c><body></c>. Un'altra cosa -- questi tags <e>non dovrebbero</e> essere
impilati -- in altre parole, non mettere un elemento <c><note></c> all'interno
di un elemento <c><p></c>. Come puoi indovinare, l'elemento <c><pre></c>
preserva esattamente i suoi spazi, diventando un ottimo elemento per pezzi di codice.</p>
</body>
</section>
<section>
<title><path>, <c> e <e></title>
<body>
<p>Gli elementi <c><path></c>, <c><c></c> e <c><e></c> possono
essere usati all'interno del tag <c><body></c>, ad eccezione di
<c><pre></c>. </p>
<p>L'elemento <c><path></c> è usato per marcare testo che si riferisce ad un
<e>file su disco</e> -- sia un percorso <e>assoluto che relativo</e>, o <e>semplicemente un nome di file</e>.
Questo elemento è generalmente rappresentato con un font monospaced per differenziarlo dal tipo
standard utilizzato nel paragrafo. </p>
<p>L'elemento <c><c></c> è usato per marcare un <e>comando</e> o <e>input
utente</e>. Pensa a <c><c></c> come ad un modod di avvertire il lettore di qualcosa
che se digitato esegue qualche tipo di azione. Per esempio, tutti
i tags XML visibili in questo documento sono racchiusi tra elementi <c><c></c>
perchè rappresentano qualcosa che l'utente potrebbe digitare
. Usando elementi <c><c></c>, aiuterai i tuoi lettori
a identificare facilmente i comandi che hanno bisogno di essere digitati. Poichè gli
elementi <c><c></c> sono bilanciati da testo regolare, <e>è raramente
necessario delimitare l'input utente tra doppi apici</e>. Per esempio, non
riferirti ad un elemento "<c><c></c>" come ho fatto in questo momento. Evitando
l'uso di doppi apici non necessari, rendiamo il documento più leggebile -- e adorabile!</p>
<p>
<c><e></c> è usato per per dare enfasi ad una parola o ad una frase; per esempio:
Dovrei usare <e>realmente</e> punti e virgola molto spesso. Come puoi vedere, questo testo è
bilanciato dal paragrafo per dare enfasi. Questo ti aiuta a dare alle
tue idee più <e>forza</e>!</p>
</body>
</section>
<section>
<title><mail> e <uri></title>
<body>
<p>Abbiamo dato un'occhiata al tag <c><mail></c> precedentemente; è usato per linkare del testo
con un particolare indirizzo email, con la seguente sintassi <c><mail link="foo@bar.com">Mr. Foo Bar</mail></c>.</p>
<p>il tag <c><uri></c> è usato per puntare a files o indirizzi
Internet. Assume due forme -- la prima può essere usata quando vuoi mostrare un
URI nel corpo del testo, come questo link a
<uri>http://www.gentoo.org</uri>. Per creare questo link, ho digitato
<c><uri>http://www.gentoo.org</uri></c>. La forma alternativa è
quando vuoi associare un URI con qualche altro testo -- per esempio, <uri link="http://www.gentoo.org" >il website Gentoo Linux</uri>. Per creare <e>questo</e>
link, ho digitato <c><uri link="http://www.gentoo.org">il website Gentoo Linux</uri></c>.
</p>
</body>
</section>
<section>
<title>Figure</title>
<body>
<p>Ecco come inserire figura in un documento -- <c><figure
link="mygfx.png" short="la mia figura" caption="la mia figura preferita
"/></c>. L'attributo <c>link=</c> punta all'attuale immagine grafica,
Lttributo <c>short=</c> specifica una descrizione (usata correntemente per
l'attributo <c>alt=</c> per le immagini HTML), e <c>caption=</c> specifica una leggenda. Non è troppo difficile
:) è supportato anche il tag stile HTML <img src="foo.gif"/>
per aggiungere immagini senza leggenda, bordi, ecc.</p>
</body>
</section>
<section>
<title>Tabelle e liste</title>
<body>
<p>Così come in HTML, il sistema Guide supporta una sintassi semplificata per le tabelle. Per iniziare
un tabella, usa un tag <c><table></c>. Comincia una riga con il tag <c><tr></c>
. Tuttavia, per inserire i dati nella tabella, <e>non</e> supportiamo il tag
HTML <td>; usiamo invece, <c><th></c> per inserire una
intestazione, e <c><ti></c> per blocchi di inforrmazioni
. Puoi usare <c><th></c> dovunque siano presenti <c><ti></c> --
non è richiesto che l'elemento <c><th></c> sia presente solo nella
prima riga. Attualmente, questi tags non supportano alcun attributo, ma presto qualcuno
sarà aggiunto (come l'attributo <c>caption=</c> per <c><table></c>).
</p>
<p> Per creare liste ordinate e non, usa semplicemente i tags stile HTML
<c><ol></c>, <c><ul></c> e <c><li></c>. I tags lista
dovrebbero apparire solo all'interno dei tag <c><p></c>, <c><ti></c>,
<c><note></c>, <c><warn></c> o <c><impo></c>. </p>
</body>
</section>
<section>
<title>Riferimenti Intra-document</title>
<body>
<p>è realmente semplice fare riferimento ad altre parti di un documento usando
hyperlinks. Puoi creare un link che punti ad <uri link="#doc_chap1" >Capitolo
1</uri> digitando <c><uri link="#doc_chap1">Capitolo
1</uri></c>. Per puntare alla <uri link="#doc_chap1_sect2" >Sezione 2 del
Capitolo 1</uri>, digita <c><uri link="#doc_chap1_sect2">Sezione 2 del
Capitolo 1</uri></c>. Per riferirsi alla Figura 3 nel Capitolo 1, digita <c><uri
link="doc_chap1_fig3">figura 1.3</uri></c>. O, per riferirsi al <uri link="#doc_chap2_pre2" >Listato 2 nel Capitolo 2</uri>,
type <c><uri link="doc_chap2_pre2">listato 2.2</uri></c>. Saranno aggiunte
presto altre funzionalità (come il supporto alle tabelle).</p>
</body>
</section>
</chapter>
<chapter>
<title>Risorse</title>
<section>
<title>Iniziare a scrivere</title>
<body>
<p>Il sistema Guide è stato progettato per essere "magro e avaro" affinchè gli sviluppatori
possano passare più tempo a scrivere documentazione e meno ad imparare la sintassi XML
. Con la speranza, che questo permetterà gli sviluppatori che non sono "grandi scrittori"
di cominciare a produrre documentazione di qualità per Gentoo Linux. Se ti piacerebbe aiutarci (o hai qualche domanda in merito),
invia un messaggio <mail link="gentoo-dev@gentoo.org" >alla gentoo-dev mailing list</mail>
e <mail link="gentoo-doc@gentoo.org" >alla gentoo-doc mailing list</mail>
dichiarando cosa ti piacerebbe fare.
Buon divertimento!</p>
</body>
</section>
</chapter>
</guide>
|
GitWeb