HOWTO HOWTO Mark F. Komarinski v0.13, 19 settembre 1999 Aiutare un nuovo autore LDP a cominciare con strumenti, idee e conven­ zioni usate da LDP. Traduzione di Mariani Dario . ______________________________________________________________________ Indice Generale 1. Introduzione 1.1 Cronologia 1.2 Nuove versioni 1.2.1 Cronologia delle versioni 1.3 Copyright e marchi registrati (in inglese) 1.4 Riconoscimenti e ringraziamenti 2. Basi su LDP e SGML 2.1 LDP 2.2 SGML 2.2.1 Perché SGML invece di HTML o di altri formati? 2.3 Gli strumenti 2.3.1 sgmltools 2.3.2 TeX 2.3.3 LyX 3. Cominciare 3.1 Per i nuovi autori 3.2 Le Mailing List 3.3 Scaricare ed installare gli strumenti 3.3.1 sgmltools 3.4 Scrivere l'SGML a mano 3.4.1 Iniziare 3.4.2 Informazioni dell'intestazione 3.4.3 Sezioni 3.4.4 Paragrafi normali 3.4.5 Testo modificato 3.4.6 Liste 3.4.7 Testo riportato 3.4.8 URL 3.4.9 Riferimenti 3.4.10 Caratteri speciali 3.5 Scrivere l'SGML utilizzando altri strumenti 3.5.1 LyX 3.5.2 Emacs 3.5.3 Altri strumenti SGML 3.6 Le basi del CVS 3.7 Distribuire la documentazione 3.7.1 Prima della distribuzione 3.7.2 Copyright e Licenze 3.7.3 Proposta a LDP 4. Suggerimenti di stile 5. FAQ su LDP 5.1 Voglio aiutare LDP. Come posso fare? 5.2 Voglio pubblicare una raccolta di documenti LDP in un libro. Come è la licenza del contenuto LDP? 5.3 Ho trovato un errore in un documento LDP. Posso correggerlo? ______________________________________________________________________ 11.. IInnttrroodduuzziioonnee 11..11.. CCrroonnoollooggiiaa Questo documento è stato iniziato il 26 Agosto 1999 da Mark F. Komarinski markk@cgipc.com dopo due giorni di frustrazione nel cercare di far funzionare gli strumenti necessari. Se almeno un autore LDP viene aiutato da questo documento, ho fatto il mio lavoro. 11..22.. NNuuoovvee vveerrssiioonnii La versione più recente di questo documento può essere trovata sulla mia homepage http://www.cgipc.com/~markk nel suo sorgente SGML. Altre versioni possono essere trovate in altri formati all'homepage di LDP http://www.linuxdoc.org/. 11..22..11.. CCrroonnoollooggiiaa ddeellllee vveerrssiioonnii vv00..2255,, 2200 sseetttteemmbbrree 11999999 · Corretti alcuni collegamenti errati · Aggiunta la sezione per i nuovi autori · Vari cambiamenti rispetto alla prima versione pubblica · Dichiarazione di copyright ora inclusa al posto di una URL vv00..1122,, 22 sseetttteemmbbrree 11999999 · Completate la maggior parte delle sezioni · Integrati dei cambiamenti dalla lista ldp-discuss vv00..1100,, 2277 aaggoossttoo 11999999 · Scritto fino alla sezione 3.4 · Aggiunto qualcosa allo schema · Cambiata la locazione della mailing list di LDP a lists.debian.org da thepuffingroup.com. vv00..0011,, 2277 aaggoossttoo 11999999 · Prima versione, creata la pagina web, scritto un semplice sommario. · Qualcosa di quello che ho scritto è da prendere con le pinze. Delle cose devono essere verificate. 11..33.. CCooppyyrriigghhtt ee mmaarrcchhii rreeggiissttrraattii ((iinn iinngglleessee)) (c) 1999 Mark F. Komarinski This manual may be reproduced in whole or in part, without fee, subject to the following restrictions: · The copyright notice above and this permission notice must be preserved complete on all complete or partial copies · Any translation or derived work must be approved by the author in writing before distribution. · If you distribute this work in part, instructions for obtaining the complete version of this manual must be included, and a means for obtaining a complete version provided. · Small portions may be reproduced as illustrations for reviews or quotes in other works without this permission notice if proper citation is given. Exceptions to these rules may be granted for academic purposes: Write to the author and ask. These restrictions are here to protect us as authors, not to restrict you as learners and educators. All source code in this document is placed under the GNU General Public License, available via anonymous FTP from the GNU archive site . 11..44.. RRiiccoonnoosscciimmeennttii ee rriinnggrraazziiaammeennttii Grazie a tutti quelli che hanno mandato commenti mentre stavo scrivendo questo documento. Questo include Deb Richardson, Daniel Barlow e altri membri della lista ldp-discuss. Alcune sezioni sono state prese dall'HOWTO Index (disponibile in molte locazioni di LDP) e la documentazione degli sgmltools. Ci sono riferimenti agli sgmltools e a LDP altrove in questo documento. 22.. BBaassii ssuu LLDDPP ee SSGGMMLL 22..11.. LLDDPP Il Linux Documentation Project (LDP) fu creato per dare ai nuovi utenti un modo per avere informazioni velocemente su di un particolare argomento. Esso non solo contiene una serie di libri su amministrazione, reti e programmazione, ma anche un gran numero di lavori minori su argomenti individuali, scritti da chi vi ha lavorato. Per trovare qualcosa sulle stampanti, basta prendere il Printing HOWTO. Per trovare qualcosa sulle reti, basta prendere l'Ethernet HOWTO, e così via. All'inizio, molti di questi lavori erano scritti in testo o HTML. Col passare del tempo, serviva un modo migliore per gestire questi documenti. Un modo che permettesse di leggerlo da una pagina web, da un file di testo su un CD-ROM o anche da un PDA. La risposta, appena esso uscì, fu l'SGML. 22..22.. SSGGMMLL Lo Standard Generalized Markup Language (SGML) è un linguaggio basato sul testo marcato. In questo modo, è simile al Tex o al groff, o a HTML. La potenza di SGML è che, diversamente dal WYSIWYG (What You See Is What You Get, quello che vedi è quello che avrai), non vengono definite cose come colori, grandezza dei caratteri o un tipo di formattazione. Invece, vengono definiti degli elementi (paragrafi, sezioni, elenchi numerati) e si lascia al processore SGML alla fine di preoccuparsi di posizione, colori, caratteri e così via. L'HTML fa la stessa cosa, ed è attualmente un subset dell'SGML L'SGML, in verità, è composto da due parti. La prima è la Struttura, chiamata comunemente DTD o Document Type Definition. Il DTD definisce le relazioni tra ognuno degli elementi. Il LinuxDoc DTD, usato per creare questo documento, ne è un esempio. Il DTD dà un aspetto comune ad ogni documento creato utilizzandolo. La seconda è il Contenuto, ovvero ciò che viene prodotto dal processore SGML e alla fine visto dall'utente. Questo paragrafo fa parte del Contenuto, ma ne farebbe parte anche un'immagine, una tabella, un elenco numerato e così via. Il Contenuto è circondato da tag per separare ogni differente elemento. Col passare del tempo, il LinuxDoc DTD sta per essere sostituito dal DocBook DTD, usato da altri, dando così all'LDP un aspetto coerente col resto della documentazione SGML. Quando questo accadrà, sarete tenuti informati tramite questo HOWTO o sulle mailing list. La differenza più grande tra LinuxDoc e DocBook, è che DocBook assegna i tag a differenti tipi di contenuto (come comandi, nomi di file, directory e così via) mentre LinuxDoc assegna i tag basandosi sul modo in cui il testo deve apparire (si può enfatizzare il testo o farlo assomigliare ad una macchina da scrivere, per esempio). 22..22..11.. PPeerrcchhéé SSGGMMLL iinnvveeccee ddii HHTTMMLL oo ddii aallttrrii ffoorrmmaattii?? L'SGML fornisce più della semplice formattazione. Si possono automaticamente costruire indici, sommari e collegamenti all'interno del documento o altrove. Il pacchetto sgmltools permette di esportare (lo chiamerò formattare da ora in poi) l'SGML in formato LaTeX, info, testo, HTML e RTF. Da questi formati di base, possono poi essere creati altri formati (DOC, PostScript e così via). L'SGML non soffre degli appesantimenti visti ultimamente nell'HTML. Non penso si vedrà molto presto un tag nell'SGML. Questo rende il codice non solo semplice da formattare, ma anche semplice da scrivere. Programmi come LyX (al momento il mio editor WYSIWYM scelto) permette di scrivere in formato TeX, esportarlo come SGML e poi formattare l'SGML ad un qualsiasi formato scelto. Per finire, l'SGML si concentra più sul modo in cui gli elementi funzionano invece che sul modo in cui appaiono. Una grossa distinzione, che permette di scrivere più velocemente, in quanto non bisogna preoccuparsi della posizione dei paragrafi, grandezza dei caratteri, tipi di carattere e così via. 22..33.. GGllii ssttrruummeennttii In questa sezione tratterò alcuni degli strumenti di cui avrete bisogno o che vorrete usare per creare la vostra documentazione LDP. Li descriverò qui e li definirò meglio più avanti, insieme alle istruzioni per l'installazione. Se utilizzate altri strumenti per aiutarvi nello scrivere materiale LDP, fatemelo sapere e aggiungerò una nota per esso. 22..33..11.. ssggmmllttoooollss Richiesti Il pacchetto sgmltools contiene gli strumenti SGML necessari per formattare l'SGML in uno dei formati di file suddetti. Contiene anche il LinuxDoc DTD, necessario per creare la documentazione LDP. Per creare solo documentazione SGML, è tutto quello che serve. Se si vuole formattare in formati quali TeX, bisogna prendere almeno questo pacchetto. Il pacchetto sgmltools è disponibile nelle distribuzioni, oppure all'indirizzo http://www.sgmltools.org/ 22..33..22.. TTeeXX Opzionale TeX (che fa rima con blech!) è il linguaggio di markup scelto da molti, incluse le persone del mondo matematico. Ancora ricordo molti esami di Calcolo scritti in TeX. È anche uno dei primi linguaggi di markup che sia ancora in giro (un altro è il formato *roff utilizzato nelle pagine man). Il TeX attualmente segue alcuni dei concetti dell'SGML. Comunque, esso compila i suoi file in DVI (DeVice Independent) che possono essere convertiti in un altro formato. Sfortunatamente, il DVI non può essere facilmente convertito in altro che alcuni linguaggi di stampanti (PostScript, PCL), rendendo difficile utilizzarlo per generare codice HTML. TeX è disponibile su praticamente tutte le distribuzioni come LaTeX o TeTeX. Dovrebbero andar bene entrambi. 22..33..33.. LLyyXX Opzionale Il programma LyX è un WYSIWYM (What You See Is What You Mean, quello che vedi è quello che intendi) grafico e fornisce un collegamento molto utile tra una applicazione grafica e un formattatore facile da utilizzare e le a volte complesse regole dell'SGML. LyX, effettivamente, serve per scrivere documenti TeX e molte delle regole del TeX si applicano in LyX. Per esempio, mentre le sezioni sono numerate automaticamente, non si possono inserire facilmente spazi bianchi (spazi e tabulazioni). È contro lo scopo per cui il TeX è stato creato. Nello stesso modo, l'SGML spesso ignora gli stessi spazi bianchi. Il programma LyX può leggere il LinuxDoc DTD e fornisce un documento modello per scrivere (o modificare) la propria documentazione LDP in modo familiare, senza dover utilizzare vi e ricordare quali sono i tag per fare un elenco puntato. LyX è disponibile all'indirizzo http://www.lyx.org/. Per chi utilizza KDE, è disponibile un port di LyX che utilizza le librerie Qt. Ulteriori informazioni possono essere trovate all'indirizzo http://www.devel.lyx.org/~ettrich/klyx.html. Se utilizzate KLyX per scrivere SGML, per favore mandate una e-mail al mio indirizzo per farmi partecipe delle vostre esperienze con esso. 33.. CCoommiinncciiaarree 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. 33..11.. PPeerr ii nnuuoovvii aauuttoorrii 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. 33..22.. LLee MMaaiilliinngg LLiisstt 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. 33..33.. SSccaarriiccaarree eedd iinnssttaallllaarree ggllii ssttrruummeennttii 33..33..11.. ssggmmllttoooollss 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. 33..44.. SSccrriivveerree ll''SSGGMMLL aa mmaannoo 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. 33..44..11.. IInniizziiaarree Per iniziare un nuovo documento, create un nuovo file nel vostro editor ASCII preferito e iniziate con: 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
e
. Questi indicano l'inizio del contenuto (o articolo, eh?). Se si è familiari con l'HTML, è simile all'includere tutto il contenuto nei tag e . 33..44..22.. IInnffoorrmmaazziioonnii ddeellll''iinntteessttaazziioonnee 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 e . L'autore è specificato nei tag e . La data usa i tag e . Le due sezioni rimanenti sono i tag e , che forniscono un sommario sul contenuto e il tag , 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:
HOWTO HOWTO Mark F. Komarinski 27 Agosto 1999 Aiutare un nuovo autore LDP a cominciare con strumenti, idee, e convenzioni usate dall'LDP 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. 33..44..33.. SSeezziioonnii 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 . 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 . Per ogni tag viene cominciata una nuova sezione. La prima sezione viene numerata con il numero 1. Le sottosezioni (come 1.1) si creano con il tag . Anche esse cominciano con 1. Le sotto-sottosezioni (1.1.1) si creano con il tag , ed anche esse cominciano con 1. Quando il processore SGML trova il tag , 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. 33..44..44.. PPaarraaggrraaffii nnoorrmmaallii Scrivere paragrafi del contenuto è proprio come l'HTML. Utilizzate un tag

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

inizia un nuovo paragrafo. Il corretto SGML prevede un tag

per chiudere il paragrafo. 33..44..55.. TTeessttoo mmooddiiffiiccaattoo 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 e . Il testo dattiloscritto va racchiuso con i tag e . 33..44..66.. LLiissttee 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ì; Questo è il primo elemento della lista numerata. Questo è il secondo. Terzo. Il tag 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. · Questo è il primo elemento della lista puntata. · Questo è il secondo. · Terzo. Il codice sopra appare così in SGML puro: Questo è il primo elemento della lista puntata. Questo è il secondo. Terzo. Come potete vedere, il tag è 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. LLDDPP The Linux Documentation Project SSGGMMLL Standard Generalized Markup Language Il codice per creare le descrizioni sopra è: LDPThe Linux Documentation Project SGMLStandard Generalized Markup Language Non è proprio uguale alle liste puntate o numerate, ma la lista è interamente racchiusa dai tag ( e ) ed ogni elemento della linea che è una parola definita va racchiusa nei tag e . Il resto della linea viene preso come la definizione della parola. 33..44..77.. TTeessttoo rriippoorrttaattoo Delle volte serve stampare il testo nel modo in cui è scritto. Per far questo, vanno usati i tag e per racchiudere il paragrafo di testo da riportare. Spazi, ritorni carrello, ed altro testo (inclusi i caratteri speciali) sono riportati letteralmente fino al tag . Il testo seguente viene riportato letteralmente . 33..44..88.. UURRLL 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 stesso. Ecco una URL che punta alla pagina principale dell' LDP: http://www.linuxdoc.org/ . Ed ecco il codice per crearla: 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ì: E sulla pagina appare come: LDP . 33..44..99.. RRiiffeerriimmeennttii 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