Il Manuale di DebianDoc-SGML
Capitolo 4 Testo marcato "in linea" e marcatori per lo stile dei caratteri

Il testo ordinario (chiamato "testo in linea" in questo documento) può contenere degli elementi per formattare in modi particolari e per riferimenti incrociati. Il testo "in linea" appare nei capitoli, appendici e titoli delle sezioni, nel sommario di copyright e all'interno di paragrafi e in altre zone simili del testo.

4.1 Stile dei caratteri

C'è un certo numero di elementi per indicare un significato speciale di certe parti del testo. Per ognuno di questi la fine del testo speciale deve essere marcata esplicitamente, usando un tag finale esplicito <elemento>, il tag finale abbreviato per chiudere l'elemento più interno </> o lo slash / che termina la forma più abbreviata di marcatura dell'elemento (vedere La struttura di un documento SGML e i metacaratteri, Capitolo 1).

<em> - enfasi

Indica che il testo contenuto è più importante o più significativo rispetto al testo che lo circonda.

Tipicamente sarà rappresentato in italico se disponibile, o in grassetto o testo sottolineato, oppure, in formati di puro testo in assenza della disponibilità di evidenziazione dei caratteri, circondando il testo con asterischi in *questo* modo.

<strong> - più enfasi

Indica che il testo contenuto è ancora più importante o ancora più significativo rispetto a quello che lo circonda.

Tipicamente sarà rappresentato in grassetto se disponibile o in formati di puro testo, in assenza della disponibilità di evidenziazione dei caratteri, circondando il testo con asterischi in *questo* modo.

<var> - variabile metasintattica

Indica che il testo contenuto è una variabile metasintattica. Cioé, \ il nome di un oggetto o parte di sintassi che quando utilizzata veramente verrebbe sostituita da un valore reale.

Tipicamente sarà rappresentato in italico, o in formati di puro testo delimitando il testo con parentesi angolari in <questo> modo. Se diverse variabili metasintattiche appaiono una di seguito all'altra, ognuna dovrebbe possedere il proprio elemento <var>.

<package> - nome pacchetto

Indica che il testo contenuto è il nome di un pacchetto Debian.

Sarà solitamente reso utilizzando un font a spaziatura fissa; in formati di puro testo possono essere usate virgolette intorno all'elemento.

<prgn> - nome di un programma o di un file molto noto

Indica che il testo contenuto è il nome di un programma, un nome di file molto conosciuto (abitualmente senza percorso o path), una funzione o una cosa simile che ha un nome sul computer.

Nei formati di output dove sono disponibili l'evidenziazione dei caratteri e vari stili di font, è usualmente rappresentato attraverso l'uso di font a spaziatura fissa. Nei formati di output in puro testo questi nomi non sono per nulla marcati in modo speciale, poiché ricorrono frequentemente e l'introduzione delle virgolette interromperebbe la scorrevolezza del testo.

<file> - nome completo di file o di directory

Indica che il testo contenuto è il percorso completo di un file, buffer, directory, ecc.

Sarà usualmente reso utilizzando un font a spaziatura fissa; in formati di puro testo possono essere usate le virgolette attorno all'elemento.

<tt> - codice o frammento di output, stringa di comando

Indica che il testo contenuto è una stringa generica che viene restituita o viene immessa nel computer. Dovrebbe essere usato per stringhe di comando o frammenti di codice che dovrebbero essere mostrati in linea e che possono andare a capo (vedere anche Esempi, Sezione 5.2 per una variante) e così via. Frequentemente è necessario introdurre variabili metasintattiche dentro queste stringhe, nel qual caso esse dovrebbero far parte dell'elemento <tt> piuttosto che essere elementi accanto ad esso.

Sarà usualmente reso usando un font a spaziatura fissa; nei formati di puro testo possono essere usate le virgolette attorno all'elemento.

<qref id="refid"> - riferimento silenzioso

Produce un `riferimento silenzioso' all'identificativo di riferimento citato (vedere Riferimenti incrociati, Sezione 4.2). Dovrebbe essere usato dove un riferimento incrociato potrebbe essere utile se non invadente, ma dove non è essenziale e dovrebbe essere tralasciato se risultasse inopportuno il suo inserimento nel testo.

Nei formati dove i riferimenti incrociati possono essere fatti in modo non invadente, rendendo una regione di testo un hyperlink senza introdurre testo in-linea, questo elemento fara sì che il testo in esso contenuto diventi un hyperlink verso la destinazione del riferimento incrociato. In altri formati questo elemento non avrà alcun effetto.

4.2 Riferimenti incrociati

Ci sono un certo numero di elementi per introdurre i riferimenti incrociati sia verso altre parti dello stesso documento che verso altri documenti.

I riferimenti incrociati interni al documento sono basati su di uno schema di identificatori di riferimento. Ogni capitolo, appendice, sezione, sotto-sezione, ecc., può avere un attributo id che fornisce il suo id di riferimento: per esempio <chapt id="spong"> specifica che il capitolo o appendice che sta per iniziare ha l'id di riferimento spong. A questo id di riferimento poi ci si può riferire in altre parti del documento usando gli elementi speciali di riferimento incrociato.

L'identificatore di riferimento sarà usato anche per generare i nomi dei file e gli elementi di riferimento per i formati come l'HTML che producono diversi file in uscita; se nessun identificatore di riferimento è specificato allora saranno usati i numeri di capitolo, di appendice e di sezione. È una buona idea fornire almeno tutti gli identificativi di riferimento di tutti i propri capitoli e appendici, così che i nomi dei file non cambieranno se si cambia l'ordine dei capitoli, appendici o sezioni nel proprio documento.

<ref id="refid"> - riferimento incrociato interno al documento

Questo genera un riferimento incrociato all'interno dello stesso documento, al capitolo, appendice o sezione con id refid.

L'elemento <ref> non ha alcun contenuto; il numero e il titolo del capitolo, appendice o sezione e il numero di pagina o qualsiasi cosa sia appropriata per il formato in uscita saranno inseriti nel testo nel punto dove appare il tag.

Sintatticamente il riferimento incrociato è un pezzo di frase con funzione di nome adatta ad usi tipo (si veda <ref id="...">) oppure ulteriori informazioni sono in <ref id="...">..

<manref name="nome" section="sezione"> - pagina di manuale

Genera un riferimento incrociato alla pagina di manuale per nome nella sezione sezione. Questo tag non ha alcun contenuto; il testo che indica la pagina di manuale, tipicamente nome(sezione), sarà inserito nel punto dove appare <manref>.

<email> - indirizzo e-mail

Indica che il testo contenuto è un indirizzo email. Il contenuto del tag dovrebbe essere solo il testo dell'indirizzo email stesso: sono proibiti marcatori di stile dei caratteri e i riferimenti incrociati. Normalmente il tag finale </email> non può essere omesso, ma può essere tralasciato quando appare in un tag <author> dato che la fine del tag <author>, implicita nell'inizio dell'elemento successivo, comporterà la fine dell'indirizzo e-mail.

In alcuni formati genererà un vero riferimento incrociato che potrebbe (per esempio) essere usato per inviare e-mail all'indirizzo indicato. In altri formati marcherà in modo speciale il testo, abitualmente includendolo tra parentesi angolari < >.

<ftpsite> - nome di un sito FTP anonimo

<ftppath> - path nel sito FTP citato più di recente

<ftpsite> indica che il contenuto dell'elemento è l'indirizzo DNS di un sito FTP anonimo, e <ftppath> indica che il contenuto è un nome di percorso in questo sito. Entrambi gli elementi non possono contenere nessun marcatore di stile dei caratteri o riferimento incrociato.

Tipicamente entrambi gli elementi saranno resi con un font a spaziatura fissa; se possibile, il <ftppath> sarà creato in forma di un hyperlink funzionante verso il file o la directory citati sul più recente <ftpsite>.

<ftppath> deve essere sempre preceduto da un <ftpsite> nello stesso capitolo o appendice, ma una volta che un sito è stato citato, possono apparire diversi percorsi.

<httpsite> - nome di un sito HTTP

<httppath> - path nel sito HTTP citato più di recente

<httpsite> indica che il contenuto dell'elemento è l'indirizzo DNS di un sito HTTP, e <httppath> che il contenuto è un nome di percorso in questo sito. Entrambi gli elementi non possono contenere alcun marcatore di stile dei caratteri o riferimento incrociato.

Tipicamente entrambi gli elementi saranno resi mediante un font a spaziatura fissa; se possibile, il <httppath> sarà creato in forma di un hyperlink funzionante verso il file o la directory citati, sul più recente <httpsite>.

<httppath> deve essere sempre preceduto da un <httpsite> nello stesso capitolo o appendice, ma una volta che un sito è stato citato, possono apparire diversi percorsi.

<url id="id" name="nome"> - URL

Genera un riferimento incrociato all'URL con l'id indicato e usa il nome opzionale nel documento come indicatore di riferimento. Questo tag non ha alcun contenuto.

Tipicamente questo elemento sarà reso mediante un font a spaziatura fissa; se possibile, l'id sarà creato in forma di un hyperlink funzionante usando nome come indicatore di posizione.

4.3 Note a piè di pagina

Le note a piè di pagina possono apparire nella maggior parte del testo "in linea" e sono indicate da <footnote>...</footnote>. Il testo stesso del piè di pagina sarà rimosso e posto altrove (dove dipende dal formato di output) e sostituito con un riferimento o un hyperlink al piè di pagina.

Il contenuto del piè di pagina dovrebbe essere uno o più paragrafi; l'inizio del primo paragrafo non è necessario sia marcato esplicitamente. Gli elementi di marcatura "in linea" come lo stile del carattere non hanno alcun effetto sul contenuto dei piè di pagina definiti al loro interno: il piè di pagina riparte da zero.

I piè di pagina possono anche essere annidati, ma questa è raramente una buona idea.