[successivo] [precedente] [inizio] [fine] [indice generale] [violazione GPL] [translators] [docinfo] [indice analitico] [volume] [parte]
Dopo la struttura generale, il sorgente Sgmltexi si articola generalmente in elementi che possono essere classificati sommariamente in blocchi e in testo interno a un blocco. Nei DTD comuni si utilizzano frequentemente le entità parametriche %block; e %inline;, per definire questi due grandi raggruppamenti. Nel DTD di Sgmltexi si usa la stessa convenzione e in questo senso vanno interpretate tali sigle nelle tabelle riassuntive.
A titolo di esempio, un blocco è qualcosa di simile a un paragrafo, un elenco, una tabella; un elemento interno alla riga è fatto per contenere del testo, eventualmente assieme a delle enfatizzazioni di qualche genere. Di solito, anche se questo fatto non può valere in generale, un elemento interno alla riga è fatto per contenere testo o altri elementi dello stesso genere; al contrario, un elemento che costituisce un blocco, può contenere altri blocchi, oppure del testo interno alla riga.
Il DTD di Sgmltexi non prevede elementi che possano contenere testo interno alla riga o blocchi a scelta, come accade invece nell'HTML.
I blocchi di testo più comuni sono dei paragrafi, delimitati dall'elemento p, il quale può apparire con un rientro iniziale o meno, a seconda dell'uso dell'attributo indent. I paragrafi, compresi quelli centrati che si ottengono con l'elemento center, contengono testo o altri elementi interni alla riga.
Tabella 257.1. Paragrafi con Sgmltexi.
Sgmltexi mette a disposizione diversi elementi il cui scopo è quello di permettere delle inserzioni per generare degli indici o dei riferimenti incrociati, riproducendo i comandi equivalenti di Texinfo.
Le voci degli indici analitici vengono inserite attraverso un gruppo di elementi vuoti: cindex, findex, vindex, kindex, pindex, tindex e userindex. Tutti questi elementi hanno lo stesso attributo entry, che serve a specificare la voce da inserire nell'indice relativo. In particolare, l'elemento userindex ha in più l'attributo name per specificare l'indice al quale si vuole fare riferimento.
Questi elementi possono essere usati solo dopo la dichiarazione di una sezione (un titolo di qualunque tipo, dal tomo in giù), ma prima del testo normale che ne seguirebbe. Per esempio così:
<h1>IP protocol history</h1> <cindex entry="IP protocol"> <cindex entry="history"> <p>Bla bla bla...</p>
La tabella 257.2 riassume brevemente l'uso di questi elementi.
Tabella 257.2. Voci degli indici analitici.
Ogni indice analitico si distingue in base a una sigla di due lettere. Gli indici analitici già previsti da Texinfo hanno una sigla fissa, mentre tutte le altre combinazioni possono essere usate per gli indici stabiliti dall'utilizzatore. La tabella 257.3 riassume le sigle degli indici standard, la cui conoscenza è necessaria per poter usare correttamente l'elemento printindex allo scopo di riprodurre l'elenco dell'indice relativo.
Tabella 257.3. Sigle identificative degli indici analitici standard.
| Sigla | Descrizione |
| cp | Indice analitico normale. |
| ky | Indice analitico dell'uso della tastiera. |
| pg | Indice analitico dei programmi. |
| fn | Indice analitico delle funzioni. |
| vr | Indice analitico delle variabili. |
| tp | Indice analitico dei tipi di dati. |
Gli elementi utilizzati per realizzare dei riferimenti incrociati sono vuoti e sono sempre interni alla riga di testo. Tutte le informazioni necessarie sono passate attraverso attributi. Dal momento che questi elementi rispecchiano fedelmente i comandi equivalenti di Texinfo, viene mostrata solo la tabella 257.4, senza entrare nel dettaglio del significato di ognuno di loro.
Tabella 257.4. Riferimenti incrociati.
In particolare, è opportuno osservare che l'attributo id degli elementi hn, partheading e tomeheading, è un'ancora a cui possono puntare tutti i vari tipi di riferimenti incrociati disponibili (tranne uref e email che puntano a degli URI).
L'esempio seguente mostra come usare l'elemento pxref in modo molto semplice:
<p>Sgmltexi crea automaticamente il nodo Top. Come già spiegato in precedenza, (<pxref id="top node menu">), il menù può essere...</p>
Un certo numero di elementi serve a delimitare parole o frasi, per qualche motivo. Il DTD di Sgmltexi è molto permissivo, in modo tale che ogni elemento di questi può contenere qualunque altro elemento interno alla riga di testo. Ciò è stato fatto per assicurare la massima compatibilità con Texinfo, ma in futuro potrebbero essere poste delle piccole limitazioni.
La tabella 257.5 elenca questi elementi, assieme a kbdinputstyle, che si usa per specificare lo stile di rappresentazione del contenuto dell'elemento kbd.
Tabella 257.5. Delimitazione di parole e frasi.
Viene mostrato un esempio molto semplice dell'uso dell'elemento strong:
<p><strong>Pinco Pallino</strong> è un uomo molto vecchio...</p> <p><strong>Tizio Tizi</strong> ha studiato tecnologia delle comunicazioni...</p>
Alcuni elementi servono a delimitare blocchi di testo, o un tipo particolare di testo interno alle righe. Il DTD di Sgmltexi è molto permissivo per assicurare la massima compatibilità con Texinfo, ma in futuro potrebbero essere poste delle piccole limitazioni.
La tabella 257.6 elenca questi elementi, assieme a pre, che permette di inserire del testo preformattato, e a exdent, utilizzato all'interno di pre per ottenere delle righe che sporgono verso l'esterno.
Tabella 257.6. Delimitazione di blocchi di testo.
In generale, l'uso di questi elementi è molto semplice, come si può vedere in questo caso:
<example> <p>Bla bla bla...</p> <p>Bla bla bla...</p> </example>
L'esempio seguente, invece, mostra l'uso dell'elemento pre, allo scopo di incorporare del testo preformattato, pur continuando a espandere le macro SGML:
<example>
<pre>
#!/usr/bin/perl
while ($line = >STDIN>)
{
chomp $line;
print ("$line\r\n");
}
</pre>
</example>
In aggiunta, si può delimitare il contenuto dell'elemento pre per poterlo scrivere in modo letterale:
<example>
<pre>
<![CDATA[
#!/usr/bin/perl
while ($line = <STDIN>)
{
chomp $line;
print ("$line\r\n");
}
]]>
</pre>
</example>
Elenchi e tabelle, sono blocchi di testo. La gestione di Texinfo per ciò che riguarda queste strutture, è abbastanza speciale. Qui viene riassunto tutto nella tabella 257.7, che però richiede la conoscenza dei comandi di Texinfo corrispondenti.
Tabella 257.7. Elenchi e tabelle.
Vengono mostrati alcuni esempi, a cominciare da un elenco non numerato:
<itemize mark="#">
<item>
<p>Primo elemento dell'elenco.</p>
<item>
<p>Secondo elemento.</p>
</itemize>
In questo caso, si ottiene un elenco puntato di due sole voci, dove al posto del pallino usuale, appare il simbolo #. Sostituendo l'elemento itemize con enumerate, si ottiene un elenco numerato:
<enumerate start="3">
<item>
<p>Primo elemento dell'elenco.</p>
<item>
<p>Secondo elemento.</p>
</enumerate>
In questo caso, si fa in modo che il primo dei due elementi abbia il numero tre. L'elenco descrittivo si ottiene attraverso l'elemento table, dove gli elementi item contengono le voci relative. Si osservi l'esempio:
<table emphasis="code">
<item>ls</item>
<itemx>dir</itemx>
<p>Elenco del contenuto della directory.</p>
<item>cd</item>
<p>Cambia directory.</p>
</table>
Si intende così che l'elemento itemx serve quando un elemento dell'elenco è composto da più di una voce.
Le tabelle, intese come quelle a cui si è abituati di solito, sono gestite attraverso l'elemento multitable. Questo, prima dell'indicazione delle righe che compongono la tabella, richiede di specificare quante sono le colonne e quanto larghe devono essere. Per questo, all'inizio occorre utilizzare una serie di elementi columnfraction, oppure columnexample, attraverso i quali si specificano proprio queste larghezze (in percentuale o attraverso un testo di esempio). L'esempio seguente mostra il caso di una tabella le cui colonne sono state definite in modo percentuale:
<multitable> <columnfraction>.30</columnfraction> <columnfraction>.70</columnfraction> <raw><strong>Parametro LOC</strong> <tab><strong>Posizione corrispondente</strong> </raw> <raw>h <tab>posizione attuale </raw> <raw>t <tab>superiore </raw> <raw>b <tab>inferiore </raw> <raw>p <tab>pagina </raw> </multitable>
In alternativa, dato che la larghezza delle colonne dipende proprio dai titoli, si poteva fare così:
<multitable> <columnexample>Parametro LOC</columnexample> <columnexample>Posizione corrispondente</columnexample> <raw><strong>Parametro LOC</strong> <tab><strong>Posizione corrispondente</strong> </raw> <raw>h <tab>posizione attuale </raw> <raw>t <tab>superiore </raw> <raw>b <tab>inferiore </raw> <raw>p <tab>pagina </raw> </multitable>
In entrambi i casi, lo scopo era quello di ottenere uno specchietto simile a quello che segue. Si osservi che non ci sono didascalie e nemmeno esiste la possibilità di collocare dinamicamente la tabella.
Parametro LOC Posizione corrispondente h posizione attuale t superiore b inferiore p pagina
Alcuni elementi sono difficilmente classificabili in gruppi particolari. Qui, vengono distinti in due raggruppamenti: quelli interni alle righe e quelli che rappresentano dei blocchi. A questi corrispondono le tabelle 257.8 e 257.9.
Tabella 257.8. Inserzioni interne alle righe.
Tabella 257.9. Inserzione di blocchi.
Texinfo prevede un grande numero di comandi per la descrizione di definizioni di vario genere. Queste «definizioni» vanno intese generalmente come dei modelli sintattici. È un po' difficile comprendere bene quando usare questa o quella forma di definizione; per cui occorre studiare la documentazione di Texinfo.
Tutte le forme di definizione si dichiarano attraverso un elemento provvisto di diversi attributi. Questo elemento contiene generalmente la descrizione del modello, in una serie di blocchi di testo, ma in particolare potrebbe contenere la descrizione degli argomenti, all'interno dell'elemento args, comune a tutte le definizioni che ne hanno.
Tabella 257.10. Definizioni; prima parte.
Tabella 257.11. Definizioni; seconda parte.
Ecco un esempio molto semplice:
<deffn cat="Command" name="sgmltexi">
<args>[<var>options</var>]... <var>sgml_source</var></args>
<p>This is the front-end for the SGML to Texinfo system.</p>
</deffn>
La composizione in formato Info genera il risultato seguente:
- Command: sgmltexi [OPTIONS]... SGML_SOURCE
This is the front-end for the SGML to Texinfo system.
Texinfo ha la possibilità di selezionare del codice in dipendenza del tipo di composizione finale. In SGML si possono fare cose simili attraverso le sezioni marcate, ma non si tratta della stessa cosa. Per questa ragione, Sgmltexi include alcuni elementi speciali corrispondenti ai comandi che servono a Texinfo per selezionare il codice, consentendo anche di inserire pezzi di codice letterale.
Tabella 257.12. Codice condizionato e codice letterale in base alla composizione.
È importante osservare che ifinfo, iftex, ifhtml, ifnotinfo, ifnottex e ifnothtml, sono elementi interni alla riga di testo, che contengono lo stesso genere di cosa. Al contrario, ifinfoblock, iftexblock, ifhtmlblock, ifnotinfoblock, ifnottexblock e ifnothtmlblock, sono blocchi che contengono altri blocchi. Questa distinzione è necessaria per evitare problemi nella definizione del documento SGML (nel DTD).
In particolare, gli elementi tex, html e texinfo, sono fatti per contenere testo letterale solitamente racchiuso tra <![CDATA[ e ]]>.
L'elemento texinfo non ha un comando equivalente in Texinfo, perché rappresenta del codice Texinfo. Si osservi l'esempio seguente:
<p>The letter <texinfo>@ubaraccent{o}</texinfo> is a special...</p>
Usando questo elemento, potrebbe essere necessario forzare l'interpretazione letterale anche da parte dell'SGML. In tal caso, il contenuto dell'elemento può essere racchiuso come si vede qui:
<p>The letter <texinfo><![CDATA[@ubaraccent{o}]]></texinfo> is a...
Il caso particolare dell'esempio non mostra una situazione in cui sia indispensabile l'interpretazione SGML letterale, tuttavia questo è il modo quando succede tale circostanza.
Viene mostrato un altro esempio nell'uso di codice letterale specifico per il tipo di composizione. L'intenzione è quella di mostrare un'espressione matematica molto semplice: 123 + 10-1.
<p><tex><![CDATA[$123+10^{-1}$]]></tex>
<html><![CDATA[123+10<sup>-1</sup>]]></html>
<ifinfo>123+10^-1</ifinfo>
= 12.3</p>
Texinfo, come TeX e *roff, distingue i blocchi di testo in quanto separati da una o più righe vuote. In tal modo, la distinzione tra blocchi di testo e testo interno alle righe, è solo una questione di spazio verticale. Per esempio, il pezzo seguente di un sorgente Texinfo, mostra tre ambienti del tipo @ifcomposizione, che sono parte dello stesso blocco di testo, ovvero lo stesso paragrafo.
La composizione attuale è @iftex TeX @end iftex @ifhtml HTML @end ifhtml @ifinfo Info @end ifinfo e si può vedere che...
In una situazione differente, questi ambienti possono diventare blocchi isolati di testo, come si vede qui:
La composizione attuale è: @iftex TeX @end iftex @ifhtml HTML @end ifhtml @ifinfo Info @end ifinfo Si può vedere che...
Con un sistema SGML, questa confusione di ruoli non è desiderabile, oltre che essere difficile da realizzare. Questo è il motivo per cui Sgmltexi distingue tra @ifcomposizione o @ifnotcomposizione, e @ifcomposizioneblock o @ifnotcomposizioneblock.
Sgmltexi cerca di mantenere le interruzioni di riga contenute all'interno del sorgente SGML, ma per questo ci sono delle conseguenze nell'uso degli ambienti condizionali, del tipo interno alle righe. Ciò dipende dal fatto che necessariamente occorre aggiungere delle interruzioni aggiuntive. Si supponga di voler scrivere qualcosa come ciò che segue:
<p>La composizione attuale è <iftex>TeX</iftex><ifhtml>HTML</ifhtml><ifinfo>Info</ifinfo>, per cui si sa cosa comporta questo fatto.</p>
Ci si aspetta che i marcatori di apertura e di chiusura vengano rimpiazzati aggiungendo anche le interruzioni di riga appropriate. Ma se fosse così, il risultato sarebbe quello seguente, in cui ciò che prima era testo interno alla riga, adesso diventa un blocco separato:
La composizione attuale è @iftex TeX @end iftex @ifhtml HTML @end ifhtml @ifinfo Info @end ifinfo , per cui si sa cosa comporta questo fatto.</p>
Per risolvere il problema, questi elementi intesi come ambienti condizionali interni alle righe, non introducono alcuna interruzione iniziale o finale che sia; rimane compito dell'autore il preoccuparsi di questo problema. Per questo, il sorgente di Sgmltexi deve essere scritto come si vede nell'esempio seguente, considerando anche che non c'è alcun modo di mettere la virgola dopo il nome del tipo di composizione.
<p>La composizione attuale è <iftex>TeX</iftex> <ifhtml>HTML</ifhtml> <ifinfo>Info</ifinfo> per cui si sa cosa comporta questo fatto.</p>
Lo stesso problema appare con gli elementi tex e html, ma in tal caso non c'è bisogno di qualificarne il contenuto, che si intende sempre come testo interno alle righe.
<p>
<tex>
$$ \chi^2 = \sum_{i=1}^N
\left (y_i - (a + b x_i)
\over \sigma_i\right)^2 $$
</tex>
</p>
|
Utilizzando un sistema SGML, l'inserzione di codice letterale per il tipo di composizione particolare che si utilizza, è da considerarsi come l'ultima risorsa. In altri termini, se sono necessari tali espedienti, è evidente che l'SGML è la scelta sbagliata per scrivere la propria documentazione. |
daniele @ swlibero.orgDovrebbe essere possibile fare riferimento a questa pagina anche con il nome sgmltexi_contenuti.html
[successivo] [precedente] [inizio] [fine] [indice generale] [violazione GPL] [translators] [docinfo] [indice analitico]