HOWTOs with LinuxDoc David S. Lawyer v0.09, November 2007 __________________________________________________________________ Questo testo tratta di come scrivere gli HOWTO usando il semplice linguaggio a marcatori (markup) LinuxDoc. È rivolto principalmente agli autori del Linux Documentation Project (e ad autori futuri alle prime armi che vogliono iniziare rapidamente). Se si vuole usare DocBook, il linguaggio a marcatori più completo e difficile, (incluso XML), vedere la LDP Authoring Guide (Guida per gli autori di LDP). Traduzione ed adattamenti in italiano a cura di Beatrice Torracca, beatricet (at) libero (dot) it, e Hugh Hartmann, hhartmann (at) libero (dot) it, revisione a cura di Vieri Giugni, v.giugni (at) gmail (dot) com). Per versioni aggiornate di questo documento, e per trovare altra documentazione in italiano sul software libero, visitare il sito dell' [1]ILDP __________________________________________________________________ 1. Introduzione 1.1 Per partire immediatamente Per imparare solamente LinuxDoc, si salti a [2]Imparare LinuxDoc. Se si vuole iniziare a scrivere immediatamente, provare a completare gli spazi vuoti in questo modello, che genera output in formato LinuxDoc: [3]The LDP HOWTO Generator. Può essere usato per iniziare a scrivere il proprio HOWTO e lo si può finire in seguito usando un editor di testi sul proprio PC. 1.2 Copyright e licenza Copyright (c) 2001-7 by David S. Lawyer. You may freely copy and distribute (sell or give away) this document. You may create a derivative work and distribute it provided that you license it in the spirit of this license and give proper credits. The author would like to receive your comments, suggestions, and plans for any derivative work based on this. 1.3 Perché si dovrebbe scrivere un HOWTO? Si conoscono cose su Linux per le quali non è disponibile nessuna buona documentazione libera e che potrebbero essere utili ad altri? Anche se non si conosce la materia approfonditamente, è sempre possibile scriverne se si ha la passione, la capacità e la volontà di imparare nuove cose su di essa e se si ha il tempo per farlo. Si è capaci di scrivere chiaramente usando un elaboratore o un editor di testi? Si vogliono aiutare migliaia di altre persone e permettere loro, senza alcun costo, di leggere ciò che si scrive? Una volta che il documento è stato scritto, si è disponibili a ricevere, via posta elettronica, suggerimenti dai lettori e ad usare selettivamente queste informazioni per migliorare il proprio HOWTO? Si è favorevoli ad avere il proprio documento disponibile su centinaia di siti web in tutto il mondo? Se si può rispondere "Sì" a queste domande, allora si è incoraggiati a scrivere qualcosa per il Linux Documentation Project (LDP); ma si sia preparati all'idea che ci potrebbe volere più tempo di quanto previsto. 1.4 Perché ho scritto questo documento Perché ho scritto questo documento quando c'è già una "LDP Authoring Guide" (Guida per gli autori LDP)? Perchè la guida LDP è un lavoro lungo e dettagliato. Se si desidera iniziare rapidamente, è necessario qualcosa di molto più semplice e breve. Grazie a Matt Welsh per il suo file example.sgml che è stato usato come fonte principale di informazioni per le sezioni di esempio. 2. Informazioni sulla scrittura di un HOWTO 2.1 Copyright Il copyright di tutti gli HOWTO e degli altri documenti LDP è dei rispettivi autori cosicché l'LDP non possiede diritti speciali sui vostri scritti. Accetta soltanto quei documenti che hanno una licenza che permetta a chiunque di copiarli e distribuirli. Incoraggia gli autori ad usare una licenza che permetta anche modifiche; in questo modo, se l'autore smette di mantenere un documento, qualcun altro può farlo. Per maggiori dettagli si guardi il "Manifesto" di LDP. 2.2 Scegliere un argomento Se non si è sicuri dell'argomento su cui scrivere, guardare alcuni dei documenti dell'LDP, inclusi quelli in [4]HOWTO non mantenuti. Si scelga un argomento per cui si prova interesse e che necessita di una buona documentazione. Se si trova qualcosa di già scritto e attualmente mantenuto che ha bisogno di essere migliorato, si cerchi per prima cosa di contattare l'autore e di sottoporre suggerimenti. Se non si riesce a contattare l'autore, si guardi la licenza per vedere se si è autorizzati a modificare il documento. Anche nei casi in cui non sia possibile fare modifiche o migliorare il documento, si può comunque scrivere un nuovo documento sullo stesso argomento partendo da zero, usando un'altra impostazione e nuove fonti di informazione. 3. Il formato degli HOWTO 3.1 Introduzione Gli HOWTO dell'LDP sono rilasciati al pubblico in vari formati: testo semplice, HTML, PostScript e PDF. Invece di dover scrivere lo stesso HOWTO in tutti questi formati, si scrive solamente un HOWTO in un formato sorgente, DocBook o LinuxDoc, che viene convertito dal computer in tutti gli altri. Per avere un'idea di come appaia questo formato basta guardare il file sorgente di una pagina web (se non lo si è già fatto). Si vedranno tante parole racchiuse tra due : queste sono chiamate "tag". Queste pagine web (tag e tutto il resto) sono in html: Hypertext Markup Language. L'LDP usa qualcosa di simile per i propri documenti. I linguaggi a marcatori che usa l'LDP soddisfano o i requisiti dello Standard Generalized Markup Language (SGML) o quelli di XML. Attualmente LDP usa le due seguenti varianti di sgml: LinuxDoc e DocBook, oltre alla variante DocBook di XML. È interessante notare che l'html nasce come un'altra variante di sgml (ma molte funzioni che vengono usate nell'html violano le regole dell'sgml, perciò non è più sgml puro). Questo mini-HOWTO è totalmente orientato all'utilizzo di LinuxDoc, una variante semplice di sgml. Si può chiamarla "linguaggio a marcatori LinuxDoc". Può essere convertita automaticamente dal computer in html, testo semplice, postscript, pdf e DocBook. È molto più semplice rispetto all'HTML o al DocBook e non è necessario un editor speciale in quanto è facile scrivere i tag (o usare macro per essi) nel proprio editor o elaboratore di testi preferito. 4. LinuxDoc e DocBook a confronto Prima di leggere questa sezione è bene avere almeno una conoscenza di base dei tag nei linguaggi di marcatura. Perciò se non si sa bene cosa siano, può essere una buona idea guardare l' [5]Esempio 1 per i marcatori di LinuxDoc. Un modo per fare un paragone è quello di analizzare HOWTO reali sul sito dell'LDP; per trovarli, fare clic su [6]Indice dei DocBook oppure su [7]Indice dei LinuxDoc. Si noterà che i documenti DocBook sono pieni zeppi di tag mentre quelli LinuxDoc hanno meno tag e sono perciò più leggibili e più facili da scrivere e modificare. Alcuni documenti sul sito LDP hanno marcatori più chiari di altri, perciò sarebbe bene guardarne più di uno. Si può inizialmente pensare che DocBook sia più avanzato poiché in esso ci sono così tanti tag in più, ma ciò non è necessariamente vero. Se si crea un documento in LinuxDoc e lo si converte in formato DocBook (con il computer) ci saranno più tag nella versione DocBook, inclusi tag nuovi che non erano presenti nella versione LinuxDoc. Perché? Perché LinuxDoc permette di omettere alcuni tag, mentre DocBook no. In questo senso LinuxDoc è più flessibile e avanzato di DocBook; non solo permette spesso di omettere i tag di chiusura come , ma permette di omettere coppie complete di tag iniziali e finali. In LinuxDoc, per esempio, i paragrafi sono separati normalmente da righe vuote invece che dalla coppia di tag

( in DocBook) e in questo modo i tag di paragrafo raramente sono necessari. Un altro esempio è l'inizio di una nuova sezione in un documento LinuxDoc; è sufficiente scrivere il titolo della sezione dopo il tag mentre DocBook richiede che si racchiuda il titolo in una coppia di tag . Quando si esegue un programma per convertire LinuxDoc in HTML, per esempio, la prima cosa che il programma fa è di cercare tutti i tag omessi e aggiungerli al documento. Viene aggiunta, per esempio, una coppia di tag equivalenti alla coppia <title> dopo un tag <sect> (inclusi i tag <sect1>, ecc.). Perciò, in un certo senso, anche LinuxDoc ha molti tag, ma sono nascosti all'utente per rendere il documento molto più facile sia da scrivere sia da leggere. Nella maggior parte dei casi, l'autore di un documento in LinuxDoc non è a conoscenza dell'esistenza della maggior parte dei tag mancanti. Non è necessario (normalmente) che l'autore li conosca, dato che esistono solo nella memoria del computer (o in un file temporaneo) quando il PC fa la conversione da LinuxDoc a un qualche altro formato (come HTML). In realtà è possibile salvare un file che mostri i tag aggiunti, ma ciò viene fatto per lo più da programmatori durante il debug di codice relativo a LinuxDoc (o da persone come me che sono curiose di sapere come funzioni). I tag DocBook sono spesso più lunghi dei loro equivalenti LinuxDoc come <emphasis> rispetto a <em>. Per un breve confronto si veda il sito web dell'autore: [8]Comparison of DocBook to LinuxDoc (Confronto tra DocBook e LinuxDoc). Il fatto che molti tag siano omessi durante la scrittura in LinuxDoc (ma vengano recuperati dal software) è tuttavia una sola delle ragioni per cui i documenti LinuxDoc hanno meno tag. Un'altra ragione è che DocBook ha in realtà molti più tag da usare di quanti non ne abbia LinuxDoc. Quest'ultimo per esempio ha un unico tag per il nome dell'autore, mentre DocBook ha tag separati per il nome, il secondo nome e il cognome. Perciò in questo senso DocBook è più potente di LinuxDoc, ma di converso è più debole perché non può recuperare i tag mancanti. La soluzione a questa dicotomia sarebbe quella di unire LinuxDoc e DocBook così da mantenere i vantaggi di entrambi. DocBook dovrebbe allora abbandonare il suo attuale stato di linguaggio "XML" poiché quest'ultimo vieta l'omissione di tag ed altro, mentre SGML lo permette. Uno dei motivi per cui non è permesso omettere tag in DocBook è che ciò rende più facile per i programmatori la scrittura di software che lo analizzi e lo converta in altri formati. Non è necessario che il software sia capace di individuare e aggiungere i tag mancanti. Fare in modo che le cose siano più semplici per i programmatori, le rende però più difficili per il molto più vasto numero di scrittori che devono usare DocBook. Ci sono editor o elaboratori di testo speciali, come Lyx e Bluefish, che rendono più facile scrivere documenti DocBook. Bluefish, per esempio, aggiunge automaticamente i tag di chiusura. Per coloro che non vogliono imparare ad usare un nuovo editor o elaboratore di testo, LinuxDoc è però molto più facile dato che si possono inserire i tag a mano o creare un insieme di macro per inserire i tag. Io uso l'editor vim e se digito ;s esso inserisce il tag <sect1>; ;r inserisce <sect>, ;i inserisce <item>, eccetera. Per i tag delle intestazioni nelle prime righe di un documento, basta copiarle da un altro documento e cambiare le parole dopo i tag. Naturalmente io non devo modificare il nome o l'indirizzo dell'autore. Un grande vantaggio di LinuxDoc è perciò di poterlo usare facilmente con lo stesso editor o elaboratore di testi normalmente utilizzato e con cui si ha familiarità. Alcune persone che non capiscono la situazione hanno sostenuto l'idea che DocBook può essere semplice come LinuxDoc semplicemente usando un sottoinsieme dei tag DocBook. Ciò non funziona perché con DocBook continua ad essere necessario un numero di tag diverse volte più grande di quello necessario per ottenere lo stesso risultato in LinuxDoc a causa del fatto che DocBook non permette l'omissione di tag. Nonostante i vantaggi di LinuxDoc, il numero di persone che usa DocBook è molto più grande di quello delle persone che usano LinuxDoc, in parte perché DocBook è stato promosso dalle case editrici. Esiste un programma di Reuben Thomas (ld2db) che può convertire documenti LinuxDoc in DocBook. Non è perfetto e molto probabilmente sarà necessario fare modifiche manuali. Inoltre l'LDP converte automaticamente un HOWTO scritto in LinuxDoc in formato DocBook, dopo che questo è stato consegnato. Sarebbe bello se esistesse un altro programma che convertisse automaticamente i documenti DocBook in LinuxDoc in modo da permettere la loro modifica usando il più semplice linguaggio a marcatori LinuxDoc. 5. Imparare LinuxDoc 5.1 Introduzione LinuxDoc è molto più facile da imparare rispetto a DocBook. Molto di ciò che si impara riguardo LinuxDoc, tuttavia, sarà utile anche per DocBook. Così, se eventualmente si decidesse di usare DocBook, la maggior parte dello sforzo speso per l'apprendimento di LinuxDoc non sarà sprecato. Un modo per imparare LinuxDoc è attraverso degli esempi. Ho scritto tre file d'esempio di difficoltà che va da facile a intermedia. Il contenuto di questi file è stato copiato in questo HOWTO. Per trasformarli in file individuali si può tagliarli dal testo (partendo dal primo tag) e scriverli in un file. Poi si può tentare di trasformarne uno in un testo semplice usando ad esempio "sgml2txt --pass="-P-cbou" un-esempio.sgml" per vedere come appare. Assicurarsi che i nomi dei file finiscano in .sgml. Se si desidera vedere alcuni esempi reali si può andare su un sito mirror di LDP, trovare gli HOWTO e selezionare LinuxDoc SGML. Oppure si può andare direttamente al sito principale: [9]Indice degli Howto (LinuxDoc). Ora il primo semplice esempio. 5.2 Esempio 1 (nome file: esempio1.sgml) <!doctype linuxdoc system> <article> <title>Primo esempio (esempio1) <author>David S.Lawyer <sect>Introduzione <p>Questo rappresenta un esempio molto semplice di "sorgente" per il sistema di formattazione testi LinuxDoc. Questo paragrafo inizia con un tag di paragrafo (una "p" racchiusa tra due parentesi angolari). Notare che ci sono altri tag, anch'essi racchiusi tra parentesi angolari. Se non si vede nessun tag, allora si sta leggendo un file convertito, si cerchi invece il file sorgente: esempio1.sgml (che contiene i tag). Questo è il paragrafo successivo. Si noti che solo una riga vuota lo separa dal paragrafo precedente. Pertanto non è necessario mettere un tag "p" al suo inizio. Il tag "p" è necessario solamente per il primo paragrafo di una sezione (appena dopo il tag di sezione). Il suffisso sgml del file significa Standard Generalized Markup Language. Quella che si sta leggendo è la variante LinuxDoc di sgml, come specificato nella primissima riga di questo file. <sect>I tag <p>I tag sono parole all'interno di parentesi angolari. Il tag "sect" qui sopra marca l'inizio di una nuova sezione di questo documento di esempio. La prima sezione era "Introduzione" e ora si sta leggendo la seconda sezione intitolata "I tag". Se questo fosse un documento lungo (come ad esempio un libro), una sezione corrisponderebbe ad un capitolo. Si noti che, all'inizio di questo articolo, ci sono i tag "article" (articolo), "title" (titolo) e "author" (autore). Alla fine di questo articolo un tag "/article" ne segna la fine. C'è dunque una coppia di tag "article", il primo è il tag d'apertura e il secondo il tag di chiusura. Una coppia di tag "article" racchiude dunque l'intero articolo. Negli esempi successivi, si vedranno altri tag che vanno in coppia come questi. Essi hanno effetto su tutto quello che si trova tra la coppia (il tag iniziale e il tag finale). Ogni tag il cui nome sia immediatamente preceduto dal simbolo "/" è un tag di chiusura. Quando questo codice sorgente viene convertito in un altro formato (come in formato testo semplice usando il programma sgml2txt) i tag vengono rimossi. I tag aiutano solamente il programma sgml2txt a fare la conversione. Ci sono molti altri tag da imparare; quando questo primo esempio è stato compreso, si passi dunque all'esempio successivo, l'esempio 2. Non si devono realmente memorizzare i tag, dato che saranno ripetuti (ma con poca o nessuna spiegazione) negli esempi successivi. </article> 5.3 Esempio 2 (nome file: esempio2.sgml) <!-- Questo è un commento. Viene ignorato quando questo file sorgente viene convertito in altri formati. --> <!-- Il tag sotto a questo indica il formato di questo file: LinuxDoc --> <!doctype linuxdoc system> <article> <title>Secondo esempio (esempio2) <author>David S. Lawyer <date>v1.0, July 2000 <abstract> Questo paragrafo rappresenta il sommario. Questo documento è il secondo esempio sull'utilizzo della variante LinuxDoc-SGML di sgml. È più complesso rispetto al primo esempio (esempio1.sgml), ma più semplice del terzo esempio (esempio3.sgml). Dopo averlo assimilato, si sarà in grado di scrivere un semplice HOWTO usando LinuxDoc. Fine del sommario. </abstract> <!-- "toc" = l'indice. Sarà creato in questo punto. --> <toc> <!-- La parte principale dell'articolo (o del documento) inizia qui. La parte soprastante rappresenta una specie di lunga intestazione. --> <sect>Questo secondo esempio (esempio2.sgml) <p>A meno che non si abbia confidenza con i linguaggi a marcatori, si dovrebbe leggere prima l'esempio 1. Potrebbe essere utile dare in pasto questi file di esempio ad un "traduttore" come sgml2txt, per convertirli in testo e notare come il risultato appaia differente ripetto a questo documento "sorgente" con tutti i suoi tag. <sect>Impaginazione dell'articolo <sect1>Corpo del documento <p>Dopo l'intestazione viene il corpo del documento, che consiste in sezioni annidate marcate dai tag di sezione ("sect"). Le sottosezioni sono marcate con i tag "sect1". Dato che questa è la prima sottosezione all'interno della seconda sezione principale, essa è la sezione 2.1. All'interno di una sottosezione marcata da "sect1" ci possono essere sotto-sottosezioni come "sect2". Ci sono persino tag come "sect3", "sect4", ecc., ma è improbabile che sia necessario usarli. Notare che i tag nell'uso reale vanno racchiusi tra parentesi angolari, < e >. <sect2>Questa è una sotto-sottosezione <p> Si tratta della sezione 2.1.1. Si noti che il tag "p" può essere su una riga da solo. Questo non cambia nulla nel documento risultante. <sect1>Intestazione del documento <p>Un modo per creare una parte di intestazione consiste nel copiarla da un altro file .sgml. Basta poi sostituire ogni cosa, eccetto i tag, con le informazioni corrette per il proprio documento. È come usare un modello. <sect>Ulteriori caratteristiche nell'esempio 3 <p>Con i tag in questo esempio 2 si può scrivere un semplice breve documento lungo qualche pagina. Ma per documenti più lunghi o per altre importanti caratteristiche, come l'inserimento di collegamenti all'interno del documento, si deve studiare l'esempio successivo, l'esempio 3. Esso mostra anche come creare elenchi e usare tipi di carattere. </article> 5.4 Esempio 3 (nome file: esempio3.sgml) <!doctype linuxdoc system> <!-- Notare il "mailto:" dopo il mio nome. Esso permette al lettore del formato HTML di cliccare sul mio indirizzo di posta elettronica per inviarmi un messaggio. --> <article> <title>Terzo esempio (esempio3) <author>David S. Lawyer <url url="mailto:dave@lafn.org"> <date>v1.0, July 2000 <abstract> Questo documento rappresenta il terzo esempio sull'uso della variante LinuxDoc di sgml. È più complesso rispetto al secondo esempio. </abstract> <!-- Commento: toc = Indice --> <toc> <sect>I tipi di carattere <p>Sebbene non compaiano nell'output in testo semplice, funzionano per altre conversioni. <bf>carattere grassetto</bf> <em>carattere enfatizzato</em> <sf>sans serif</sf> <sl>carattere inclinato</sl> <tt>carattere a spaziatura fissa</tt> <it>carattere corsivo</it> Un altro modo per ottenere questi stessi tipi di carattere consiste nel racchiudere il testo con il simbolo "/", in questo modo: <bf/carattere grassetto/ <em/carattere enfatizzato/ <sf/sans serif/ <sl/carattere inclinato/ <tt/carattere a spaziatura fissa/ <it/carattere corsivo/ Si noti che DocBook non ha tag per i tipi di carattere dunque sarebbe meglio non usarli se si ha in progetto di fare la conversione in DocBook. <sect>I collegamenti <label id="links_"> <p>Si possono creare collegamenti (qualcosa su cui si può cliccare all'interno di un navigatore html per andare da qualche altra parte). Possono indirizzare semplicemente in un'altra parte di questo documento (riferimenti incrociati), tipo l'etichetta ("label") qui sopra, oppure possono indirizzare ad un sito web in Internet. <sect1>Riferimenti incrociati <p>Se si clicca su <ref id="links_" name="Collegamenti"> si viene spostati all'inizio della sezione precedente "I collegamenti" (che è etichettata come "links_"). L'etichetta può essere una qualsiasi parola liberamente scelta, ma è buona norma evitare parole comuni, in modo da poter cercare etichette univoche usando il proprio editor. Per questa ragione è stato usato links_ (con il simbolo di sottolineatura). Il nome di questo collegamento viene mostrato (nel formato html) come il nome su cui fare clic. Questo nome (Collegamenti) è presente anche nella versione in puro testo. <sect1>Collegamenti con URL <p>Se si clicca su <url url="http://www.tldp.org"> si viene spostati sul sito web del Linux Documentation Project. Il successivo collegamento aggiunge un nome su cui gli utenti cliccano: <url url="http://www.tldp.org" name="Linux Documentation Project">. Usando questo secondo metodo, non si deve nemmeno spiegare dove porta il collegamento, in quanto è ovvio dal nome. <sect>Caratteri proibiti <p>Ogni parola scritta tra parentesi angolari viene interpretata come un tag. Come fare allora per mostrare un tag in un documento? Per questo scopo si usa una parola in codice per i caratteri delle parentesi angolari. Si può usare < per il simbolo < e > per il simbolo >. lt = "less than" (minore di), gt = "greater than" (maggiore di). Per esempio, questo è un tag p: <p>. Naturalmente di fatto non inizia alcun paragrafo, ma appare nei documenti convertiti come <p>. Tutti questi codici iniziano con un carattere "&". Il carattere ";" posto dopo lt serve per separarlo. Non è necessario se c'è uno spazio dopo di esso. Ad esempio: 3 < 4. Di fatto, se si sapesse che va bene usare un > disaccoppiato si potrebbe scrivere <p> come <p>. Questo non sarebbe riconosciuto erroneamente come tag, dato che non c'è l'apertura <. A dire il vero anche 3 < 4 funziona bene. Ci sono altri caratteri che non si possono mettere direttamente nel testo del documento. Per il carattere "&" in un comando AT del modem usare: AT&. Se altri caratteri danno dei problemi (lo fanno raramente) si veda <ref id="ch_codes" name="Codici dei caratteri (macro)"> o la "guida" che viene fornita con linuxdoc-tools o sgml-tools. <sect>Verbatim, codice e a capo <sect1>Verbatim <p>Se si vuole essere sicuri che il testo appaia esattamente come lo si è digitato, anche dopo la conversione in altri formati, usare il tag verbatim "verb". È utile per creare tabelle, e simili. Tuttavia alcune cose vengono comunque riconosciute come marcatori anche se si trovano tra tag verbatim. Tra queste sono incluse le macro che iniziano con il carattere "&" e i tag finali con il carattere "/". <tscreen><verb> % sgml2txt --pass="-P-cbou" esempio.sgml </verb></tscreen> Il tag "tscreen" imposta il carattere a spaziatura fissa e imposta il rientro in modo bello da vedersi. <sect1>Codice <p>Questo racchiude del codice del computer tra due righe tratteggiate. <tscreen><code> Mettere il codice sorgente qui. </code></tscreen> <sect1>A capo <p>Per andare a capo in modo forzato usare <newline> Questa frase inizia sempre al margine sinistro. <sect>Elenchi <p>Questo mette elementi dentro ad un elenco puntato con un segno grafico all'inizio di ogni elemento. Gli elenchi iniziano con il tag "itemize". <itemize> <item>Questo è il primo elemento di un elenco. <item>Questo è il secondo elemento. <itemize> <item>Sono supportati livelli multipli (annidati). <item>Il secondo elemento in questo sottoelenco. </itemize> <enum> <item>Funzionano anche elenchi numerati usando <tt/enum/. <item>Questo è l'elemento numero 2. </enum> <item>Questo è l'ultimo elemento nell'elenco principale. </itemize> </article> 5.5 Guida di consultazione rapida di LinuxDoc Intestazione <!doctype linuxdoc system> <article> <title>Guida di consultazione rapida <author>David S. Lawyer <date>v1.0, July 2000 <abstract>Qui va messo il sommario </abstract> <toc> <!-- Commento: toc = Indice --> Impaginazione del corpo <sect>Capitolo 1 Nota: si metta un <p> sulla prima riga di <sect1>Sottosezione 1.1 ogni sezione (o sottosezione, ecc.) <sect1>Sottosezione 1.2 <sect>Capitolo 2 Si scelgano nomi di titoli da sostituire a <sect1>Sottosezione 2.1 "Capitolo", "Sottosezione", ecc. <sect2>Sotto-sottosezione 2.1.1 <sect2>Sotto-sottosezione 2.1.2 <sect1>Sottosezione 2.2 </article> Tipi di carattere Ci sono due modi per ottenerli: <bf>carattere grassetto</bf> <em>carattere enfatizzato</em> <sf>carattere sans serif</sf> <sl>carattere inclinato</sl> <tt>carattere a spaziatura fissa</tt> <it>caratter e corsivo</it> oppure: <bf/grassetto/ <em/enfatizzato/ <sf/sans serif/ <sl/inclinato/ <tt/spaziatura fissa/ <it/corsivo/ Elenchi (è possibile l'annidamento) Normali elenchi non numerati: Elenchi numerati: <itemize> <enum> <item>Primo elemento <item>Primo elemento <item>Secondo elemento <item>Secondo elemento <item>eccetera <item>eccetera </itemize> </enum> Collegamenti Riferimenti incrociati: Un collegamento email: <ref id="links_" name="Collegamenti"> <url url="mailto:bob@tldp.org"> A capo, verbatim, URL Per andare a capo forzatamente: <newline> <tscreen><verb> <url url="http://www.tldp.org"> <url url="http://www.tldp.org" name="Linux Documentation Project">. </verb></tscreen> Codici di carattere (macro) Non è sempre necessario usarli. * Usare & per la e commerciale (&). * Usare < per una parentesi angolare sinistra (<). * Usare > per una parentesi angolare destra (>). * Usare &etago; per una parentesi angolare sinistra con una sbarra (</). L'uso di questi è opzionale e io li uso raramente. * Usare `` e '' per aprire e chiudere apici doppi. * Usare ­ per un soft-hyphen (trattino debole), per indicare cioè che questo è un buon punto per spezzare una parola molto lunga e inserire un trattino per la giustificazione orizzontale della riga. Usare i seguenti solo se si hanno problemi in LinuxDoc con essi o se non si riesce ad ottenerli nel documento formattato. Io ho dovuto usarli raramente. * Usare $ per il simbolo del dollaro ($). * Usare # per il simbolo cancelletto (#). * Usare % per il simbolo di percentuale (%). * Usare ˜ per la tilde (~). * Usare &dquot; per ". 6. Ottenere/Usare il software LinuxDoc Si potrebbe scrivere un documento LinuxDoc senza avere alcun software LinuxDoc. Tuttavia è assai probabile che esso contenga errori nei tag (o nel loro uso), così da vederselo restituire per le correzioni. Anche se non ci fossero errori, il risultato potrebbe non apparire nel modo esatto. Perciò è meglio avere sul proprio computer il software per convertire il proprio file sorgente. La distribuzione di Linux Debian ha un pacchetto linuxdoc-tools. Esiste anche un pacchetto rpm per distribuzioni diverse da Debian. Precedentemente si chiamava sgml-tools; non si utilizzi il pacchetto sgmltools-2 perché è destinato principalmente per DocBook. Per usare linuxdoc-tools, si eseguono i programmi di conversione sui file *.sgml. Per esempio, per ottenere un file di testo con una versione successiva alla 0.9.21-0.8 digitare: "sgml2txt -f --blanks=1 mio-HOWTO.sgml". Per le versioni precedenti, a causa di un bug, si deve sostituire -f con --pass="-P-cbou". (Se interessati a maggiori informazioni su questo bug, guardare [10]Il vecchio problema con le sequenze di escape nell'output in testo semplice.) Per ottenere output html digitare: "sgml2html mio-HOWTO.sgml". Se appaiono degli errori, saranno mostrati il numero della riga e della colonna corrispondenti alla posizione dell'errore nel file sorgente. Digitando "man -k sgml" dovrebbe apparire un certo numero di altri programmi con una descrizione di una riga per ciascuno, ma non tutti sono per linuxdoc-sgml. 7. Errori e messaggi di errore 7.1 Errori che non creano messaggi di errore Un errore importante è quello di dimenticare di mettere un tag <p> dopo l'intestazione di una sezione. In quel caso non c'è una fine dell'intestazione della sezione: tutto il paragrafo successivo diventa parte dell'intestazione e viene inserito nell'indice. LinuxDoc dovrebbe essere migliorato per poter individuare questo tipo di errori; per farlo manualmente, si guardi l'indice in formato testuale o html. Per correggere basta inserire il tag "p" mancante. 7.2 Messaggi di errore Quando si esegue un programma linuxdoc (sgml2html o sgml2txt, per esempio) è possibile che si ottengano messaggi di errore. È necessario modificare il documento e correggere gli errori. Un errore comune è la mancanza delle virgolette finali. Se si ottiene un messaggio di errore che non ha senso e si nota che nella posizione corrispondente all'errore sono presenti delle virgolette (" ") che sono corrette, allora è probabile che l'errore consista nell'aver in precedenza inserito una virgoletta di apertura a cui non ne corrisponde una di chiusura. Ad esempio <.... id="mia pagina web >, così che linuxdoc pensa che la virgoletta successiva, che può anche essere molti paragrafi dopo la posizione della virgoletta mancante, sia la virgoletta di chiusura. Dopo la falsa virgoletta di chiusura si aspetta quindi un carattere > che chiuda il tag, ma non lo trova. Per trovare e correggere la virgoletta mancante, si ricerchi una " precedente. Un unico errore può causare molti messaggi di errore. Nell'esempio precedente, vari tag possono essere contenuti all'interno delle virgolette sbagliate mentre non avrebbero dovuto essere all'interno di alcuna virgoletta. Di conseguenza linuxdoc non li troverà; ciò fa sì che non sappia che un certo tag è stato aperto e, se trova un tag di chiusura, dirà che un certo tag non è stato aperto. Per esempio, se mancasse il tag <itemize>, allora i tag <item> non avrebbero senso per linuxdoc ed esso riporterà un errore per ciascuno di questi tag trovato dopo la falsa virgoletta di chiusura. È bene sapere che l'uso delle maiuscole o minuscole per i nomi dei tag non è importante, perciò i messaggi di errore saranno mostrati con i nomi dei tag in maiuscolo anche se sono stati inseriti in lettere minuscole. Capire al meglio i messaggi di errore richiede la conoscenza del gergo relativo all'sgml, il che non è veramente necessario a meno che non si ottengano errori che non si riescono a correggere e dei quali non si capisce il messaggio di errore. La sezione seguente tratta del gergo sgml. 8. Gergo nei messaggi di errore 8.1 Introduzione Non è veramente necessario leggere questa sezione a meno che non si abbiano problemi oppure non si abbia la curiosità di sapere come funzionano l'sgml e linuxdoc. I messaggi di errore possono contenere parole come "element" (elemento), "entity" (entità, o "entities" al plurale), "attribute" (attributo), "literal" (letterale) e "delimiter" (delimitatore). Vari elementi, entità e attributi sono definiti per linuxdoc nel "Data Type Definition" (o DTD) per LinuxDoc. Il DTD non li definisce a parole, ma usa un formato piuttosto criptico per definire la loro sintassi (ma non la loro semantica). 8.2 Gli elementi Un "elemento" è un qualcosa come un tag, ma è un concetto molto più ampio. Gli elementi esistono non solo in LinuxDoc, ma in tutti i linguaggi sgml, come ad esempio html. L'intero documento LinuxDoc è diviso in elementi, ma questi sono annidati; questo significa che alcuni elementi possono comparire all'interno di altri elementi. Se si usa il tag <article> per il proprio documento, allora tutto il documento è l'elemento <article>, tranne per il primissimo tag che dice che ciò che segue è LinuxDoc. All'interno di tale elemento "article" sono annidati molti altri elementi. Ogni paragrafo, per esempio, è un elemento, anche se i paragrafi sono separati tra di loro da una riga vuota invece che da tag. C'è però un tag implicito che racchiude ogni paragrafo ed il software che analizzerà il documento LinuxDoc di fatto inserirà questi tag mancanti. Inserirà anche i tag finali (di chiusura) dove non era obbligatorio scriverli. In questo modo LinuxDoc fa risparmiare molto tempo. Un elemento consiste perciò in un tag di apertura, in uno di chiusura (corrispondente a quello di apertura) e a tutto ciò che è racchiuso tra di essi (compresi spesso altri elementi con i loro tag). Si noti che i tag anche se omessi sono tuttavia sempre implicitamente presenti. In alcuni casi un tag non racchiude alcunché, come un tag URL per un collegamento Internet; questi tag sono essi stessi elementi. All'interno dell'elemento "article" si trovano elementi "sect" (sezioni) che iniziano con <sect>. All'interno degli elementi "sect" ci sono poi spesso elementi "sect1", ecc. Ci sono alcuni casi in cui è presente un elemento, ma è opzionale l'uso sia del tag di apertura, sia di quello di chiusura. Perciò anche se tale tag non è presente nel documento, le parti del documento che avrebbbe dovuto racchiudere sono comunque elementi di quei tag mancanti. Un'entità è come una definizione di macro. Per esempio, si potrebbe definire il nome "elenco" come significativo dei vari tipi di elenchi. Questa parola elenco viene poi usata nel DTD solo per specificare, per esempio, che è possibile avere un elenco all'interno di un paragrafo. È semplicemente un'abbreviazione per l'autore di un DTD. Questo tipo di entità non è mai usato in un documento LinuxDoc. Esiste però anche un altro tipo di entità che può essere usata all'interno di un documento ed è quella che definisce un carattere speciale come &etago per </ (inizio del tag di chiusura). Lo si usa, per esempio, quando si desidere mettere </article> all'interno di una frase per spiegare cosa significa, in modo che il software che converte il LinuxDoc non pensi che sia davvero la fine dell'articolo. 8.3 Literal e delimitatori Un "literal" è il nome di qualcosa, come il nome su cui si clicca in un collegamento html; può essere formato da una o più parole. Un delimitatore è ciò che separa qualcosa da qualcos'altro. Per una "citazione" l'ultima " è il delimitatore di chiusura. Perciò per name="mio sito web", il "literal" è 'mio sito web' e i delimitatori di questo "literal" sono i due caratteri ": il primo " è il delimitatore di apertura e il secondo " il delimitatore di chiusura. Così la frase "manca il delimitatore di chiusura di un literal" significa che ci si è dimenticati di inserire un " finale dopo un nome. 9. Scrivere l'HOWTO 9.1 Prima di iniziare a scrivere Per prima cosa ci si iscriva alla lista di discussione andando all'indirizzo [11]www.en.tldp.org e si sottoponga la propria proposta a questa lista. Se si prende in carico un HOWTO non più mantenuto, si contatti l'autore precedente. Ciò può essere richiesto dal copyright/licenza, ma andrebbe fatto in ogni caso come forma di cortesia. 9.2 Linee guida Queste sono principalmente opera di Tim Bynum (un ex-coordinatore degli HOWTO). * Assicurarsi di usare un formato accettato (come il LinuxDoc :-). * Cercare di usare una struttura e un'organizzazione significativa, e scrivere chiaramente. Ricordare che molte delle persone che leggono gli HOWTO non parlano l'inglese come loro prima lingua. * Assicurarsi che tutte le informazioni siano corrette. Non insisterò mai abbastanza su questo punto. Nel dubbio, si facciano delle congetture, ma si sia chiari sul fatto che si stanno facendo solamente delle ipotesi. Io uso ?? se non sono sicuro. * Assicurarsi di trattare la più recente versione del software disponibile. * Prendere in considerazione l'inclusione di una sezione "FAQ" oppure delle sezioni "Problemi comuni" o "Risoluzione di problemi". * Assicurarsi di mettere nel copyright il proprio nome e di includere una licenza che soddisfi i requisiti dichiarati nel manifesto di LDP. * Usare l'intestazione standard con il titolo, l'autore, la data (includendo un numero di versione). Si veda [12]Esempio 3. * Da ultimo, prepararsi a ricevere messaggi di posta elettronica con domande e commenti dei lettori. Sta alla propria discrezione quanto aiutare gli altri, ma si dovrebbero ascoltare i buoni suggerimenti e le segnalazioni di errori. Si potrebbero anche ricevere dei messaggi di ringraziamento. 9.3 Sottoporre l'HOWTO, ecc. Dopo aver scritto l'HOWTO, inviare via posta elettronica il sorgente SGML all'indirizzo: submit@tldp.org. Successivamente tutto ciò che è necessario fare è tenere aggiornato l'HOWTO sottoponendo periodicamente gli aggiornamenti allo stesso indirizzo di posta usato per la prima edizione. 10. Ulteriori informazioni C'è un HOWTO, il Linuxdoc Reference, che tratta LinuxDoc in modo molto più dettagliato di quanto non faccia questo mini-HOWTO. 11. Appendice 11.1 Il vecchio problema con le sequenze di escape nell'output in testo semplice Prima della versione 0.9.21-0.8 c'era un bug nell'output in formato di testo semplice. Per sgml2txt, era necessaria l'opzione --pass="-P-cbou" per ottenere l'output in puro testo dato che altrimenti, se si usava l'opzione -f, si otteneva un output di testo che metteva l'enfasi sulle parole e sulle lettere usando sequenze di escape e sovrascrittura. L'esempio di un pallino creato con la sovrascrittura è +^Ho che in una stampante stamperebbe "+", poi tornerebbe indietro di uno spazio (^H, backspace) e quindi stamperebbe "o" sopra al "+" esistente. Questo non sembra funzionare sui terminali (non possono sovrascrivere). Notare che anche se si ha la versione più recente, si ottiene sempre questo output non voluto se non si usa l'opzione -f. In caso si sia interessati ai dettagli, --pass passa l'opzione -P-cbou al programma groff (usato da sgml2txt) e l'opzione -P di groff passa le opzioni -cbou a grotty (un post-elaboratore per groff), forzandolo a generare solamente output in puro testo. Vedere la pagina di manuale di grotty. In breve, -c evita le sequenze di escape, ma permette la sovrascrittura, -bou tuttavia proibisce la sovrascrittura quando è usata l'opzione -c. Il risultato è l'assenza di sovrascritture e di sequenze di escape nell'output. -b proibisce la sovrascrittura per far apparire un carattere in grassetto, -u previene l'uso della sovrascrittura per sottolineare e -o proibisce altri tipi di sovrascrittura quale l'esempio del pallino sopra citato. Un modo alternativo per eliminare la sovrascrittura è di usare l'opzione -f con sgml2txt, ma è sempre necessario passare l'opzione -c a grotty per eliminare le sequenze di escape, a meno che non si abbia la versione più recente. Che confusione! L'opzione predefinita dovrebbe probabilmente essere il puro testo, così da rendere tutte queste opzioni non necessarie. Finalmente sono riuscito a far correggere tutto ciò, perciò da metà 2007 in poi, si può usare solamente l'opzione -f invece di --pass="-P-cbou". Se si ottengono queste sequenze di escape e sovrascritture nel proprio file di output, ma si usa il comando Linux "cat" per visualizzare il testo, il risultato è molto bello. L'uso di paginatori o di editor sul file output di testo tuttavia ha spesso come risultato danni ai caratteri di escape, così che si vedono nel proprio testo un mucchio di caratteri non desiderati, che avrebbero dovuto far parte delle sequenze di escape. In alcuni casi i paginatori possono mostrare alcune sovrascritture correttamente, ma gli editor (come vim) non lo fanno. Eliminare tutte le sovrascritture permette perciò di usare un qualsiasi editor o paginatore per leggere. References 1. http://it.ildp.org/ 2. file://localhost/home/giulio/HOWTO/Howtos-with-LinuxDoc/Howtos-with-LinuxDoc.html#learn_ 3. http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html 4. http://www.tldp.org/authors/unmaint.html 5. file://localhost/home/giulio/HOWTO/Howtos-with-LinuxDoc/Howtos-with-LinuxDoc.html#example_1 6. http://cvs.tldp.org/go.to/LDP/LDP/howto/docbook/ 7. http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/ 8. http://www.lafn.org/~dave/linux/ld_vs_db.txt 9. http://cvs.tldp.org/go.to/LDP/LDP/howto/linuxdoc/ 10. file://localhost/home/giulio/HOWTO/Howtos-with-LinuxDoc/Howtos-with-LinuxDoc.html#esc_seqs 11. file://localhost/home/giulio/HOWTO/Howtos-with-LinuxDoc/www.en.tldp.org 12. file://localhost/home/giulio/HOWTO/Howtos-with-LinuxDoc/Howtos-with-LinuxDoc.html#example_3