Questa sezione mostra come venire coinvolti nello scrivere la propria documentazione LDP. Come ottenere e configurare gli strumenti, contattare LDP e distribuire le proprie conoscenze a tutti gli utenti Linux ovunque.
Se si è nuovo di LDP e si vuole rilevare un HOWTO non mantenuto o scrivere un nuovo documento HOWTO o mini-HOWTO, contattare il coordinatore degli HOWTO all'indirizzo linux-howto@metalab.unc.edu. Questo per essere sicuri che il coordinatore degli HOWTO venga a sapere chi sta lavorando e su quale documentazione. Notare che anche tutti gli HOWTO proposti devono essere in formato SGML (utilizzando il DocBook DTD o il LinuxDoc DTD). I mini-HOWTO proposti possono essere sia 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 iscriversi, mandare un messaggio con oggetto "subscribe" all'indirizzo ldp-discuss-request@lists.linuxdoc.org. Per ritirare la propria adesione, mandare una e-mail con oggetto "unsubscribe" a ldp-discuss-request@lists.linuxdoc.org.
Scaricare il pacchetto sgmltools da http://www.sgmltools.org/ o direttamente dalla propria distribuzione. I file del sorgente da sgmltools.org sono nel formato di codice sorgente, così si dovranno compilare per la propria macchina. Usando un pacchetto precompilato per la propria distribuzione è più semplice, così non è necessario compilarlo e incorrere a potenziali problemi di compilazione (è così, se non si è programmatori).
Con la RedHat, sgmltools è incluso nella distribuzione. Altrimenti, lo si può scaricare da ftp.redhat.com o da qualsiasi altro dei suoi mirror come parte della distribuzione principale.
Se si utilizza la Debian, anche essa ha sgmltools nella distribuzione standard. Se non si ha il pacchetto installato, si può utilizzare il comando apt-get per scaricare ed installare il pacchetto automaticamente:
# apt-get install sgmltools
Per maggiori informazioni sui pacchetti Debian, si può guardare al http://www.debian.org/Packages/stable/text/sgml-tools.html.
Se si stà compilando il codice sorgente, tutto ciò che è necessario è:
# tar -zxvf sgmltools-x.x.x.tar.gz # cd sgmltools-x.x.x # ./configure # make # make install
Sostituire sgmltools-x.x.x con la versione attuale del pacchetto
sgmltools che si sta utilizzando. Al momento di questa publicazione, la
versione corrente che supporta LinuxDoc è la 1.0.9. La versione che
supporta il DocBook è la 2.0.2. Entrambe sono disponibili al sito web
riportato sopra.
Una volta che gli strumenti sono installati, è disponibile un certo numero di comandi.
sgmlcheck file.sgml - Verifica 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 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 editor grafico.
Questo è ottimo se si hanno file SGML pre-generati e si vogliono convertire
per l'uso con LyX.
Come con HTML, è possibile scrivere SGML a mano, non appena si conoscono tutti i codici di marcatura (tag) che si vogliono usare. Questa sezione illustrerà la maggior parte possibile di questi codici, insieme ad esempi pratici di ognuno. Un buon esempio per iniziare potrebbe essere il sorgente SGML di questo documento, che è disponibile al sito web riportato nell' Introduzione. Anche se SGML può essere elaborato in modi diversi a seconda del formato del file in cui viene convertito, proverò ad elencare alcune cose che è bene conoscere durante la stesura.
Per iniziare un nuovo documento, creare un nuovo file nel proprio editor ASCII preferito e iniziare con questo (tag):
<!doctype linuxdoc system>
Questo (tag) definisce il tipo di documento (LinuxDoc nel nostro caso) che il interprete SGML userà quando renderà il file in un formato di uscita. Questo tag non produce nulla in uscita.
Poi è necessario racchiudere il resto del proprio lavoro tra i tag
<article> e </article>. Questo significa
l'inizio del contenuto (o articolo, eh?). Se si ha confidenza con l'HTML,
questo è simile a racchiudere tutto il proprio contenuto tra i tag
<html> e </html>.
La prima parte del contenuto dovrebbe contenere informazioni generali riguardanti il resto del contenuto. Questo potrebbe essere simile alle prime pagine di un libro, dove si trova la pagina del titolo (titolo del lavoro, autore, data di pubblicazione, tavola dei contenuti, e così via).
Il titolo del contenuto è racchiuso tra i 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 esecutivo riguardo al
contenuto e il tag <toc>, che specifica la posizione dell'indice
o tavola dei contenuti (TOC). La TOC viene generata automaticamente dal interprete
SGML. Le sezioni verranno discusse più avanti.
Ora, come appare tutto insieme? Preso un bel frammento di codice SGML (cioè quello che è stato usato per creare questo documento), si vedrà:
<!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>v1.1, 14 Dicembre 1999 </date> <abstract>Elenca gli strumenti, le procedure e fornisce consigli per condurre rapidamente all'efficienza gli autori di HOWTO. </abstract> <toc>
Questo frammento del contenuto ha creato la pagina principale che si vede quando si guarda questo documento nel formato RTF o HTML, elencando tutte le informazioni in una pagina.
Per costruire la tavola dei contenuti, è necessario avere qualcosa con cui costruirla. Le sezioni, nel caso dell'SGML, equivalgono ai capitoli nelle pubblicazioni tradizionali. Sono disponibili sezioni multiple e ogni sezione può avere una sottosezione e ognuna di queste può avere una sottosezione e così via.
Iniziare il proprio documento con le sezioni è comodo, in quanto permette di creare un profilo degli argomenti principali che si vogliono trattare. Poi si possono dividere queste sezioni principali in sezioni gradatamente più piccole, fino ad ottenere delle piccole parti di cui si può scrivere in pochi brevi paragrafi. Ho proprio 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 riguardo alla numerazione. L'interprete SGML gestirà
pienamente la numerazione quando il file l'SGML verrà trasformato in un
altro formato.
Le sezioni iniziano con il tag <sect>. Una nuova sezione viene
iniziata con ogni tag <sect>. La prima sezione viene numerata con
il numero 1.
la creazione di sottosezioni (come 1.1) è fatta con il tag
<sect1>. Anche esse iniziano con il numero 1.
Le sotto-sottosezioni (1.1.1) si creano con il tag <sect2>,
ed anche esse cominciano con il numero 1.
Quando il l'interprete SGML trova il tag <toc>, finisce
il resto del documento e costruisce la tavola dei contenuti basata sul numero
dei tag di sezione contenuti al suo interno. Le sezioni vengono numerate ed
elencate nella TOC e poi utilizzate nel resto del documento. Le sotto-sottosezioni
(1.1.1) non vengono mostrate nella TOC, ma sono rese in testo enfatizzato, se
possibile.
Scrivere paragrafi del contenuto è proprio come nell'HTML. Utilizzare
un tag <p> per specificare una nuova riga e cominciate a scrivere.
L'SGML ignorerà 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 che si metta un tag </p> per chiudere il
paragrafo.
Qualche volta potrebbe essere necessario un po' di testo diverso dal resto.
Sia per evidenziare del codice che per il nome di un comando. Il primo
(il testo enfatizzato) si ottiene con i tag <em> e </em>.
Il testo dattiloscritto (il secondo esempio) si ottiene con i tag <tt>
e </tt>.
Ci sono due modi per realizzare le liste in SGML. Il primo è la lista numerata, dove ogni elemento nella lista viene numerato (come le sezioni) cominciando con il numero 1.
Il codice per la lista sopra appare come il seguente:
<enum> <item>Questo è il primo elemento della lista numerata. <item>Questo è il secondo. <item>Terzo. </enum>
Il tag <enum> specifica che gli elementi seguenti verranno
numerati.
L'altro metodo di scrivere liste è la lista a punti o puntata, dove ogni elemento ha una stella, un cerchio, un punto o qualche altro metodo per evidenziare tale elemento.
Il codice sopra appare come il seguente nell'SGML grezzo:
<itemize> <item>Questo è il primo elemento della lista puntata. <item>Questo è il secondo. <item>Terzo. </itemize>
Come si può vedere, il tag <item> è lo stesso
per la lista numerata e quella a punti.
Un terzo tipo 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>
Questo è un po' differente rispetto alle liste puntate o numerate, ma
la lista èinteramente racchiusa dai tag (<descrip> e
</descrip>) ed ogni elemento nella linea, che è una parola
definita, va racchiusa nei tag <tag> e </tag>.
Il resto della linea viene preso come la definizione della parola.
Qualche volta è necessario stampare solo una parte del testo nel modo
in cui è scritto. Per far questo, si possono usare i tag <verb>
e </verb> per racchiudere il paragrafo di testo da riportare.
Spazi, ritorni carrello, ed altro testo (inclusi i caratteri speciali) sono
preservati fino al tag </verb>.
Questo è un testo riportato letteralmente.
Anche nell'SGML è possibile gestire Localizzatori Universali di Risorse (URL o Universal Resource Locator) di ogni tipo. Notare che essi dovrebbero funzionare solamente quando esportati nel modo HTML, ma gli altri formati possono usare questi tag altrettanto bene.
Un URL non ha un tag di chiusura, ma mette le sue informazioni tra il tag
<url> stesso. Questo è un URL che punta alla pagina
principale dell'LDP:
http://www.linuxdoc.org/.
E qui c'è il codice per crearlo:
<url url="http://www.linuxdoc.org/" name="http://www.linuxdoc.org/">
url="http://www.linuxdoc.org/" comunica al browser dove
andare, mentre il contenuto di name="http://www.linuxdoc.org/"
comunica al browser cosa visualizzare sullo schermo. In questo caso, i due sono
simili, ma è possibile creare un tag URL che appare come il seguente:
<url url="http://www.linuxdoc.org/" name="LDP">
E sulla pagina appare come: LDP. Tuttavia, la buona regola suggerisce di duplicare l'URL nella porzione del nome. Il motivo di questo è che se qualche volta si usa un'uscita di testo (TXT) o di RTF, il tag sopra potrebbe non avere significato. Non si potrebbe sapere quale URL usare.
Mentre i tag URL sono ottimi per collegarsi con i contenuti esterni al
documento di LDP a cui si sta lavorando, non sono adatti per collegarsi
all'interno del contenuto stesso. Per questo scopo, si usano i tag
<label> e <ref>. Il tag <label>
crea un punto nel documento a cui riferirsi poi, come un segnalibro. Creare i
tag <label> è semplice. Si trovi il punto al quale ci si
vuole riferire successivamente, e si inserisca il seguente:
<label id="Introduction">
Ora si è creato un punto nel documento al quale ci si può riferire in seguito come "Introduction". Questa etichetta appare attualmente nel lavoro SGML all'inizio del documento. Quando ci si vuole riferire a quel punto in seguito (ad esempio qui), si inserisca il seguente tag:
<ref id="Introduction" name="qui">
e l'SGML inserirà un collegamento chiamato "qui" (vedi sopra) che rimanda alla locazione della sezione "Introduzione".
L'altro scopo dei riferimenti è l'indicizzazione. Dato che la documentazione LDP viene usualmente pubblicata su carta come una grande raccolta di documenti, c'è la necessità di avere un modo per costruire l'indice in fondo al libro, basato su parole e soggetti.
Come in HTML, ci sarà la necessità di evadere (escape) molti caratteri non-alfanumerici per impedire all'interprete SGML di interpretarli come codice SGML. Ecco una lista di codici SGML utilizzati. Altri sono nella Guida Utente sgmltools localizzata a http://www.sgmltools.org/guide/guide.html.
L'autore di questo HOWTO va ancora in solluchero per LyX. Si d'accordo, è poco obbiettivo verso questa applicazione perché gli piace per davvero. 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 capita dopo che l'interprete SGML ha finito di lavoraci su.
Per creare un documento LinuxDoc con LyX, scaricare ed installare l'applicazione.
Prima assicurarsi di avere TeX e gli sgmltools installati (per maggiori informazioni
vedere
Scaricare ed installare gli strumenti).
Una volta finita l'installazione, avviare LyX e selezionare "file->new from template..."
Selezionare "Templates" poi fare click su linuxdoctemplate.lyx e si
avrà impostato un modello di documento, con la maggior parte delle
informazioni di intestazione che un documento LDP dovrebbe avere.
Cambiare i dati per addattarlo alle proprie necessità (ovvero, inserire
il Titolo, Autore, Data, Sommario e così via) e poi iniziare a scrivere.
Il menu a comparsa nell'angolo in alto a destra può essere usato per
selezionare tipi di contenuto (standard, liste puntate e numerate, sezioni). Il
punto esclamativo è usato per enfatizzare il testo e si può fare
click su di esso e iniziare a scrivere in modo enfatizzato, oppure evidenziare
il testo con il mouse e fare click su di esso per enfatizzare il testo evidenziato.
Sotto la barra del menu Insert possono essere trovate molte altre caratteristiche.
Si possono inserire locazioni di URL, riferimenti incrociati, elementi dell'indice
e altri tipi di dati. Quando la propria documentazione è completata, si
può salvarla nel formato LyX, poi esportarla in LinuxDoc ed avere il file
salvato con un'estensione .sgml. Poi questo file è pronto per essere
verificato con sgmlcheck e convertito nei formati voluti.
Emacs ha un modo di scrittura SGML chiamato psgml. Chiunque abbia esperienza di scrittura con questo modo è incoraggiato a inviare una email all'autore di questo documento.
Se ci sono altri strumenti SGML, oltre questi, anche commerciali, con i quali possa essere usato il LinuxDoc DTD per creare la documentazione LDP, per favore, fatelo sapere all'autore.
LDP stà trattando per fornire accesso al CVS agli autori. Ci sono alcune buone ragioni per utilizzare il CVS:
Se si è completamente inesperti del CVS, ci sono un po' di pagine in rete che si possono leggere e che possono essere di aiuto:
Prima, sarà necessario ottenere un account al Repository CVS dell'LDP. Questo è praticamente la root directory che è usata dal CVS, con vari progetti (HOWTO, mini HOWTO, ecc.) creati come sottodirectory di di questa.
Sarà necessario creare una password hashed e un userid per il proprio account. La password hashed permette di inviare una password criptata al gruppo del CVS dato che non c'è la necessità di conoscere la propria password Si può fare questo con il seguente comando, da bash (o sh):
$ echo mettere_la_propria_password_qui | perl -e "print crypt(<>, join '',('.', '/',
0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\""
Prendere il risultato di questo comando e inviarlo con il proprio userid proposto al cvsadmin@cvslist.linuxdoc.org. Il proprio unico CVSROOT sarà creato e si otterrà una e-mail con un responso. Quando si ottiene il proprio responso, fare il login dentro il proprio CVSROOT e assicurarsi che ogni cosa sia impostata propriamente:
$ export CVSROOT=:pserver:proprio_userid@cvs.linuxdoc.org:/cvsroot $ cvs -d $CVSROOT login
(Sostituire il CVSROOT con quello che era stato inviato in risposta alla e-mail).
Verrà richiesta la propria password e poi sarà dato l'acesso al Repository CVS in modo lettura-scrittura. Dopo aver effettuato il login del cvs e che sia stato dato l'accesso al sistema, la propria password viene immagazzinata nel file .cvsroot e non si dovrà usare ancora il login del cvs. Basta impostare il CVSROOT and continue on. Si può ottenere l'intero repository linuxdoc con questo comando:
$ cvs get LDP
O si può ottenere il sorgente SGML per proprio documento con questi comandi:
$ cvs get howto/Il_PROPRIO-HOWTO.sgml $ cvs get minihowto/PROPRIODOC.sgml
È anche disponibile la Commit List, dove si invia una e-mail per ogni cambiamento apportato in qualsiasi parte nel repository. Notare che questa è una lista ad alto traffico. È possibile iscriversi inviando una mail vuota al commits-subscribe@cvslist.linuxdoc.org. È possibile revocare la propria iscrizione inviando una mail vuota al commits-unsubscribe@cvslist.linuxdoc.org.
È disponibile l'accesso al CVS anonimo (solo lettura):
$ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login
Come password, usare cvs. Poi si possono ottenere i moduli di linuxdoc come sopra. Notare che i cambiamenti al sito anoncvs possono essere indietro di una mezz'ora al sito principale.
Si può accedere al repository CVS attraverso la rete al http://cvsweb.linuxdoc.org/index.cgi/linuxdoc.
Ci sono delle interfacce grafiche al CVS, si può ottenere una lista di queste al http://freshmeat.net/appindex/. Ricercare il CVS.
CVS ha un tag speciale che si può usare per inserire automaticamente la data e la versione direttamente nel documento. Questo è chiamato $Id$. Includendo questo tag (per esempio) nel proprio tag <date>, si può avere un cambiamento automatico ogni volta che si cambia il file, permettendo al segno di revisione di venire incrementato ogni volta.
Quando si è pronti per caricare i cambiamenti al server CVS, usare il comando:
cvs ci -m "commento" PROPRIO-HOWTO.sgml. Il
-m "commento"non è necessario, ma se non viene incluso, si dovrà entrare nell'editor (usualmente vi, o qualsiasi cosa sia la propria variabile d'ambiente EDITOR) e sarà data la possibilità di aggiugere un commento riguardo ai cambiamenti.
È possibile seguire molte discussioni riguardo il CVS sulla lista ldp-discuss. Per il momento, per sottoporre la propria documentazione all'LDP si dovrà ancora indirizzare a ldp-submit.
Prima di distribuire il codice a milioni di potenziali lettori ci sono dei passi da seguire.
Primo, assicurarsi di controllare l'ortografia del documento. La maggior parte delle utilità che si usano per scrivere in SGML (emacs, LyX, altri editor di testo) hanno dei plug-in per fare un controllo ortografico. Altrimenti, c'è sempre il programma ispell, installato praticamente in ogni distribuzione. Utilizzare anche il comando sgmlcheck degli sgmltools per verificare se si hanno i tag SGML corretti.
Secondo, fare leggere a qualcuno la propria 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 si fa parte di una grande mailing list, dove si tratta lo stesso soggetto, chiedere aiuto agli altri della lista.
Terzo, creare un sito web dove poter distribuire la documentazione. Non è obbligatorio, ma è utile per le persone per trovare la locazione originale del proprio 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, si può 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 si sceglie di utilizzare il copyright di quel documento, copiarlo semplicemente nel proprio codice sorgente in una sezione chiamata "Copyright e Licenze" o simile. Includere anche una dichiarazione di copyright propria (in quanto ancora lo si possiede). Se si è un nuovo mantenitore di un HOWTO già esistente, si deve 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 sono stati presi in considerazione i loro commenti, in generale, si può rilasciare il proprio documento a LDP. Inviare una email a ldp-submit@lists.linuxdoc.org con il proprio sorgente. Assicurarsi che il nome dell'HOWTO sia stato inserito nella linea del subject. Qualora non si abbia risposta entro sette giorni, si è pregati di inviare una e-mail per assicurarsi che il processo sia ancora in corso.