Avanti Indietro Indice

3. Cominciare

Questa sezione mostra come venire coinvolto nello scrivere la propria documentazione LDP. Come ottenere e configurare gli strumenti, contattare LDP e distribuire le proprie conoscenze a tutti gli utenti Linux là fuori.

3.1 Per i nuovi autori

Se siete nuovi di LDP e volete prendere un HOWTO non mantenuto o scrivere un nuovo documento HOWTO o mini-HOWTO, contattate il coordinatore degli HOWTO all'indirizzo linux-howto@metalab.unc.edu. Questo per essere sicuri che il coordinatore degli HOWTO sappia chi sta lavorando su quale documento. Notate anche che tutti gli HOWTO proposti devono essere in formato SGML (al momento utilizzando il LinuxDoc DTD). I mini-HOWTO proposti possono essere in formato SGML o HTML, ma solo quelli formattati in SGML potranno essere inclusi nelle versioni stampate degli HOWTO.

3.2 Le Mailing List

Ci sono delle mailing list alle quali iscriversi per sapere come funziona LDP. La prima è ldp-discuss@lists.linuxdoc.org, che è il maggiore gruppo di discussione di LDP. Per iscrivervi, mandate un messaggio con oggetto "subscribe" all'indirizzo ldp-discuss-request@lists.linuxdoc.org. Per deiscrivervi, mandate una e-mail con oggetto "unsubscribe" a ldp-discuss-request@lists.linuxdoc.org.

3.3 Scaricare ed installare gli strumenti

sgmltools

Scaricate il pacchetto sgmltools da http://www.sgmltools.org/ o direttamente dalla vostra distribuzione. I file da sgmltools.org sono in codice sorgente, per cui dovete compilarli per la vostra macchina. Utilizzare un pacchetto precompilato per la propria distribuzione è più semplice, in quanto non bisogna compilarlo e potenzialmente ricevere errori di compilazione (è così, se non siete programmatori).

Con la RedHat, gli sgmltools sono inclusi nella distribuzione. Altrimenti, potete scaricarli da ftp.redhat.com o un altro dei suoi mirror come parte della distribuzione principale.

Se utilizzate la Debian, anche essa ha gli sgmltools nella distribuzione standard. Se non avete il pacchetto installato, potete utilizzare il comando apt-get per scaricare ed installare il pacchetto al posto vostro: 

# apt-get install sgml-tools

Per maggiori informazioni sui pacchetti Debian, potete andare all'indirizzo http://www.debian.org/Packages/stable/text/sgml-tools.html.

Se state compilando il codice sorgente, tutto quello che dovete fare è: 

 # tar -zxvf sgmltools-x.x.x.tar.gz
 # cd sgmltools-x.x.x
 # ./configure
 # make
 # make install

Sostituite sgmltools-x.x.x con la versione attuale del pacchetto sgmltools che state utilizzando. Mentre sto scrivendo, la versione che supporta LinuxDoc è la 1.0.9. Quella che supporta il DocBook è la 2.0.2. Entrambe sono disponibili al sito web riportato sopra.

Una volta che gli strumenti sono installati, sono disponibili una serie di comandi.

sgmlcheck file.sgml - Controlla la sintassi di un dato documento.

sgml2html file.sgml - Converte un file SGML in HTML. Crea un file file.html che contiene l'Indice, poi crea i file file-x.html, dove x è il numero della sezione.

sgml2rtf file.sgml - Converte un file SGML in formato Rich Text Format (RTF). Crea due file, il primo chiamato file.rtf che contiene la TOC (Indice), ed uno chiamato file-0.rtf, che contiene tutte le sezioni.

sgml2txt file.sgml - Converte un file SGML in testo ASCII. La TOC e tutte le sezioni sono messe tutte nel file file.txt.

sgml2info file.sgml - blabla SGML blabla INFO, utilizzato dal comando info. Tutto l'output viene messo nel file file.info.

sgml2latex file.sgml - blabla SGML blabla TeX.

sgml2lyx file.sgml - SGML yadda LyX graphical editor. Ottimo se si hanno SGML pre-generati e si vogliono convertire per l'uso con LyX.

3.4 Scrivere l'SGML a mano

Come con HTML, è possibile scrivere SGML a mano, quando si conoscono i codici di marcatura (tag) che si vogliono utilizzare. Questa sezione illustrerà più tag possibile, con esempi pratici di ognuno. Un buon posto da dove iniziare può essere il sorgente SGML di questo documento, che è disponibile all'indirizzo riportato nell' Introduzione. Anche se SGML può essere processato in modi diversi a seconda del formato del file in cui viene convertito, proverò ad elencare delle cose da sapere durante la scrittura.

Iniziare

Per iniziare un nuovo documento, create un nuovo file nel vostro editor ASCII preferito e iniziate con: 

<!doctype linuxdoc system>

Questo definisce il tipo di documento (LinuxDoc nel caso nostro) che il processore SGML utilizzerà in fase di formattazione del file nel formato di uscita. Questo tag non produce nulla in uscita.

Poi bisogna chiudere il resto del lavoro nei tag <article> e </article>. Questi indicano l'inizio del contenuto (o articolo, eh?). Se si è familiari con l'HTML, è simile all'includere tutto il contenuto nei tag <html> e </html>.

Informazioni dell'intestazione

La prima parte del contenuto dovrebbe contenere informazioni generali sul resto del contenuto. Vorrebbe essere simile alle prime pagine di un libro, dove troviamo titolo, autore, data di pubblicazione, indice, eccetera.

Il titolo del contenuto è chiuso nei tag <title> e </title>. L'autore è specificato nei tag <author> e </author>. La data usa i tag <date> e </date>.

Le due sezioni rimanenti sono i tag <abstract> e </abstract>, che forniscono un sommario sul contenuto e il tag <toc>, che specifica la posizione della TOC. La TOC viene generata automaticamente dal processore SGML. Vedremo le sezioni più tardi.

Ora, come appare tutto insieme? Preso questo bel pezzo di codice SGML (utilizzato per creare questo documento), si può vedere: 

<!doctype linuxdoc system>
<!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <markk>
 Fri Aug 27 09:42:28 1999 -->
<article>
<title>HOWTO HOWTO</title>
<author>Mark F. Komarinski</author> 
<date>27 Agosto 1999 </date> 
<abstract>Aiutare un nuovo autore LDP a cominciare con strumenti, idee, e
 convenzioni usate dall'LDP</abstract> 
<toc>

Questo pezzo del contenuto ha creato la pagina principale che è possibile vedere guardando questo documento in formato RTF o HTML, mettendo tutte le informazioni in una pagina.

Sezioni

Per costruire l'Indice, bisogna avere qualcosa con cui costruirlo. Le sezioni nel caso dell'SGML sono l'equivalente dei capitoli nelle pubblicazioni tradizionali. Sono disponibili sezioni multiple e ogni sezione può avere sottosezioni e ognuna di esse può avere sottosezioni eccetera.

Cominciare i documenti con le sezioni è comodo in quanto permette di creare una bozza degli argomenti principali da coprire. Poi si possono spezzare queste sezioni principali in sezioni gradatamente più piccole, fino ad ottenere delle piccole parti di cui si può scrivere in pochi piccoli paragrafi. Ho cominciato così a scrivere questo documento.

Le sezioni sono uno dei pochi insiemi di tag SGML che non richiedono di essere chiusi. Non ci sono tag </sect>. E non c'è bisogno di preoccuparsi della numerazione. Ci penserà il processore a gestirla quando l'SGML verrà formattato in un altro formato.

Le sezioni cominciano con il tag <sect>. Per ogni tag <sect> viene cominciata una nuova sezione. La prima sezione viene numerata con il numero 1.

Le sottosezioni (come 1.1) si creano con il tag <sect1>. Anche esse cominciano con 1.

Le sotto-sottosezioni (1.1.1) si creano con il tag <sect2>, ed anche esse cominciano con 1.

Quando il processore SGML trova il tag <toc>, passa attraverso il resto del documento e costruisce l'Indice basato sul numero dei tag di sezione ivi contenuti. Le sezioni vengono numerate e elencate nella TOC e poi utilizzate nel resto del documento. Le sotto-sottosezioni (1.1.1) non vengono mostrate nella TOC, ma sono mostrate in testo enfatizzato se possibile.

Paragrafi normali

Scrivere paragrafi del contenuto è proprio come l'HTML. Utilizzate un tag <p> per specificare una nuova riga e cominciate a scrivere. L'SGML ignora gli spazi bianchi come tabulazioni, spazi multipli e ritorni a capo. Quando l'SGML incontra un tag <p> inizia un nuovo paragrafo. Il corretto SGML prevede un tag </p> per chiudere il paragrafo.

Testo modificato

Ogni tanto potrebbe servire un poco di testo diverso dal resto, per evidenziare del codice o per un comando. Il testo enfatizzato va racchiuso con i tag <em> e </em>. Il testo dattiloscritto va racchiuso con i tag <tt> e </tt>.

Liste

Ci sono due modi per fare liste in SGML. Il primo è la lista numerata, dove ogni elemento della lista viene numerato (come le sezioni) cominciando con 1.

  1. Questo è il primo elemento della lista numerata.
  2. Questo è il secondo.
  3. Terzo.

Il codice per la lista sopra appare così; 

<enum>
<item>Questo è il primo elemento della lista numerata. 
<item>Questo è il secondo.
<item>Terzo.
</enum>

Il tag <enum> specifica che gli elementi seguenti saranno numerati.

L'altro metodo di scrivere liste è la lista puntata, dove ogni elemento ha una stella, un cerchio, un punto o un altro metodo per puntare gli elementi.

Il codice sopra appare così in SGML puro: 

<itemize>
<item>Questo è il primo elemento della lista puntata.
<item>Questo è il secondo.
<item>Terzo. 
</itemize>

Come potete vedere, il tag <item> è lo stesso per la lista numerata e quella puntata.

Una terza forma di lista è la lista descrittiva. Essa ha un termine descritto e una frase che lo descrive.

LDP

The Linux Documentation Project

SGML

Standard Generalized Markup Language

Il codice per creare le descrizioni sopra è: 

<descrip>
 <tag>LDP</tag>The Linux Documentation Project
 <tag>SGML</tag>Standard Generalized Markup Language
 </descrip>

Non è proprio uguale alle liste puntate o numerate, ma la lista è interamente racchiusa dai tag (<descrip> e </descrip>) ed ogni elemento della linea che è una parola definita va racchiusa nei tag <tag> e <tag>. Il resto della linea viene preso come la definizione della parola.

Testo riportato

Delle volte serve stampare il testo nel modo in cui è scritto. Per far questo, vanno usati i tag <verb> e </verb> per racchiudere il paragrafo di testo da riportare. Spazi, ritorni carrello, ed altro testo (inclusi i caratteri speciali) sono riportati letteralmente fino al tag </verb>. 

Il testo seguente viene riportato letteralmente       .

URL

Anche nell'SGML è possibile gestire Universal Resource Locator (URL) di ogni tipo. Notate che essi funzionano solamente quando esportati in HTML, ma ci possono essere degli usi per questo tag in altri formati (lo usa anche l'RTF?).

Una URL non ha un tag di chiusura, ma mette queste informazioni tra il tag <url> stesso. Ecco una URL che punta alla pagina principale dell' LDP: http://www.linuxdoc.org/. Ed ecco il codice per crearla: 

<url url="http://www.linuxdoc.org/" name="http://www.linuxdoc.org/">

url="http://www.linuxdoc.org/" dice al browser dove andare, mentre i contenuti di name="http://www.linuxdoc.org/" dicono al browser cosa scrivere sullo schermo. In questo caso, i due sono simili, ma è possibile creare un tag URL che appare così: 

<url url="http://www.linuxdoc.org/" name="LDP">

E sulla pagina appare come: LDP.

Riferimenti

Mentre le URL sono ottime per collegarsi con i contenuti esterni al documento a cui si sta lavorando, non sono molto comode per collegarsi con il contenuto stesso. Per questo, si usano i tag <label> e <ref>. Il tag <label> crea un punto nel documento a cui riferirsi poi, come un segnalibro. Creare il tag <label> è semplice. Posizionatevi nel punto al quale volete riferirvi poi, e inserite il seguente: 

<label id="Introduction">

Avete ora creato un punto nel documento al quale potete riferirvi dopo come "Introduction". Questa etichetta attualmente appare in questo SGML all'inizio del documento. Quando volete riferirvi a quel punto più tardi (ad esempio qui), inserite il seguente tag: 

<ref id="Introduction" name="qui">

e l'SGML inserirà un collegamento chiamato "qui" (vedi sopra) che rimanda alla sezione "Introduzione".

L'altro scopo dei riferimenti è l'indicizzazione. Siccome la documentazione LDP viene solitamente pubblicata su carta come una grande raccolta di documenti, serve un metodo per costruire l'indice in fondo al libro, basato su parole e oggetti.

Caratteri speciali

Come in HTML, c'è bisogno di fare l'escape di molti caratteri non-alfanumerici per impedire al processore SGML di interpretarli come codice SGML. Ecco una lista di codici SGML utilizzati. Altri sono nella Guida Utente sgmltools http://www.sgmltools.org/guide/guide.html.

3.5 Scrivere l'SGML utilizzando altri strumenti

LyX

Mi sto ancora entusiasmando troppo per LyX. Okay, sono un poco obbiettivo verso questa applicazione perché mi piace veramente. Fornisce la potenza di scrivere in SGML con la facilità di un normale word processor. Non è un programma WYSIWYG, ma un'applicazione più WYGIWYM (What You Get Is What You Mean, quello che ottieni è quello che intendi), in quanto quello che si vede sullo schermo non è necessariamente quello che si ottiene dopo che il processore SGML l'ha elaborato.

Per creare un documento LinuxDoc con LyX, scaricate ed installate l'applicazione. Assicuratevi di avere TeX e gli sgmltools installati (vedere Scaricare ed installare gli strumenti per maggiori informazioni). Una volta finito, avviate LyX e selezionate "file->new from template..." Selezionate "Templates" poi fate click su linuxdoctemplate.lyx e avrete pronto un modello di documento, con la maggior parte delle informazioni di intestazione che dovrebbe avere un documento LDP. Cambiate i dati per soddisfare i vostri bisogni (ovvero, inserite il Titolo, Autore, Data, Sommario, eccetera) e cominciate a scrivere. Il menu a comparsa nell'angolo in alto a destra può essere utilizzato per selezionare tipi di contenuto (standard, liste puntate e numerate, sezioni). Il punto esclamativo viene utilizzato per enfatizzare il testo e potete o farci click sopra e cominciare a scrivere in modo enfatizzato oppure selezionare il testo con il mouse e farci click per enfatizzare il testo selezionato. Molte altre caratteristiche possono essere trovate sotto il menu Insert. Potete inserire url, riferimenti incrociati, elementi dell'indice e altri tipi di dato. Quando la documentazione è completata, potete salvarla in formato LyX, poi esportarla in LinuxDoc ed avere il file salvato con un'estensione .sgml. Questo file è poi pronto per essere verificato con sgmlcheck e convertito nei formati voluti.

Emacs

Ho questa cosa su Emacs. Non lo uso e la cosa non mi irrita. Chiunque con più esperienza di Emacs sarebbe molto utile.

Altri strumenti SGML

Se ci sono altri strumenti SGML, anche commerciali, con le quali possa essere utilizzato il LinuxDoc DTD per creare la documentazione LDP, fatemelo sapere.

3.6 Le basi del CVS

Al momento, l'LDP non ha un deposito condiviso per archiviare i contenuti online. Speriamo che la cosa cambi. Ci sono alcune buoni ragioni per utilizzare CVS:

  1. Il CVS mantiene un backup off-site dei documenti. Nel caso cediate un documento ad un altro autore, lui può recuperare il documento dal CVS e continuare. Nel caso ci fosse bisogno di tornare ad una versione precedente di un documento, anche esso può essere recuperato.
  2. È comodo se ci sono molte persone che lavorano sullo stesso documento. È possibile farsi dire dal CVS quali cambiamenti sono stati fatti da un altro autore mentre stavate modificando la vostra copia e integrare quei cambiamenti.
  3. Tiene traccia dei cambiamenti fatti. Questi log (ed una data) possono essere inseriti automaticamente nel documento utilizzando dei tag speciali che vengono processati prima che il documento venga processato dal processore SGML.
  4. Fornisce un metodo per un programma di aggiornare automaticamente il sito web LDP con nuova documentazione appena viene scritta e proposta.

3.7 Distribuire la documentazione

Prima della distribuzione

Prima di distribuire il codice a milioni di potenziali lettori ci sono dei passi da seguire.

Primo, assicuratevi di controllare l'ortografia del documento. Nulla dice "Sì, sono stupido!" più velocemente degli errori di scrittura nella terra di Internet. La maggior parte delle utilità che utilizzate per scrivere in SGML (emacs, LyX, altri editor di testi) hanno dei plug-in per fare un controllo ortografico. Altrimenti, c'è sempre il programma ispell, installato in praticamente ogni distribuzione. Utilizzate anche il comando sgmlcheck degli sgmltools per verificare i tag SGML.

Secondo, fate leggere a qualcuno la vostra documentazione per commenti e correttezza formale. La documentazione pubblicata da LDP deve essere il più possibile corretta, in quanto ci sono milioni di utenti Linux che potrebbero leggerla. Se fate parte di una grossa mailing list che parla dello stesso soggetto, chiedete agli altri della lista di aiutarvi.

Terzo, create un sito web dove poter distribuire la documentazione. Non è obbligatorio, ma è utile per le persone per trovare la locazione originale del vostro documento.

Copyright e Licenze

Perché un documento LDP sia accettato dall'LDP, deve avere una licenza che permetta la libera distribuzione (come la birra) e pubblicazione. Come autore, potete detenere il copyright ed aggiungere altre restrizioni (per esempio, il dover approvare ogni traduzione o lavori derivati). Una licenza d'esempio è disponibile all'indirizzo http://www.linuxdoc.org/COPYRIGHT.html. Se scegliete di utilizzare il copyright di quel documento, copiatelo semplicemente nel vostro codice sorgente in una sezione chiamata "Copyright e Licenze" o simile. Includete anche una dichiarazione di copyright propria (in quanto ancora lo possedete). Se siete un nuovo mantenitore per un HOWTO già esistente, dovete includere la dichiarazione di copyright dell'autore/i precedente/i e le date in cui loro mantenevano il documento.

Proposta a LDP

Quando il documento LDP è stato riletto da alcune persone e avete preso in considerazione i loro commenti, potete rilasciare il vostro documento a LDP in generale. Mandate una email a ldp-submit@lists.linuxdoc.org con il vostro sorgente. Entro 24 ore dovreste sapere se è stato accettato e inserito nel sito principale di LDP.

Avanti Indietro Indice

Hosting by: hurra.com
Generated: 2007-01-26 17:56:13