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.
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.
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.
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.
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.
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>.
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.
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.
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.
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>.
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.
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.
The Linux Documentation Project
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.
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 .
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.
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.
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.
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.
Ho questa cosa su Emacs. Non lo uso e la cosa non mi irrita. Chiunque con più esperienza di Emacs sarebbe molto utile.
Se ci sono altri strumenti SGML, anche commerciali, con le quali possa essere utilizzato il LinuxDoc DTD per creare la documentazione LDP, fatemelo sapere.
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:
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.
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.
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.