Capitolo 274.   Stile di scrittura del sorgente

Il DTD di Alml suggerisce una logica nella stesura del sorgente. In questo capitolo si annotano dei suggerimenti sulla sistemazione degli elementi nel sorgente, allo scopo di ottenere una struttura ordinata, in funzione delle caratteristiche di questi.

274.1   Blocchi di testo e rientri

In generale, un blocco di testo viene scritto a partire dalla prima colonna del file, oppure viene incolonnato più a destra, di quattro caratteri alla volta, se si tratta di un sottoblocco di qualche tipo. Si osservi l'esempio seguente:

<frame>

    <p>Bisogna fare attenzione alle...
    ...
    ...</p>

</frame>

L'elemento frame serve a contenere uno o più blocchi interni; questi vanno indicati con un rientro.

I blocchi di testo con un contenuto di tipo %inline;, ovvero testo ed elementi interni al testo, dovrebbero mostrare la loro natura, avvolgendo il testo, senza aggiungere rientri ulteriori. Per esempio, si usa l'elemento p in questo modo:

<p>Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla...</p>

Al contrario, sarebbe spiacevole scrivere una cosa del genere:

<p>
    Bla bla bla bla...
</p>

I blocchi di testo, allineati in base alla necessità, vanno poi organizzati in modo da evitare di uscire dalla portata visiva di uno schermo normale; in pratica dovrebbero trovarsi entro le prime 80 colonne, come nell'esempio seguente:

<frame>

    <p>I blocchi di testo, allineati in base alla necessità, vanno poi
    organizzati in modo da evitare di uscire dalla portata visiva di uno
    schermo normale; in pratica dovrebbero trovarsi entro le prime
    <num>80</num> colonne.</p>

</frame>

Per favorire l'uso di funzionalità adatte del proprio programma di scrittura, allo scopo di reimpaginare i paragrafi e gli altri blocchi di testo, è necessario staccare i blocchi di testo tra di loro e dal loro contenitore.

274.1.1   Elenchi

Gli elenchi di Alml sono definiti in modo da contenere sempre blocchi di testo. In tal modo, la struttura più coerente con quanto affermato a proposito dei rientri e dell'impaginazione dei blocchi, è quella dello schema seguente per ciò che riguarda gli elenchi puntati e numerati:

<ul>|<ol>
<li>

    blocco

    [blocco]
    ...

</li>
[<li>

    blocco

    [blocco]
    ...

</li>]
...
</ul>|</ol>

Per gli elenchi descrittivi, la situazione è abbastanza simile:

<dl>
<dt>voce</dt>
<dd>

    blocco

    [blocco]
    ...

</dd>
[<dt>voce</dt>
<dd>

    blocco

    [blocco]
    ...

</dd>]
...
</dl>

In modo equivalente si comporta anche l'elemento segment:

<segment>
<segmenthead>titolo</segmenthead>

    blocco

    [blocco]
    ...

[<segmenthead>titolo</segmenthead>

    blocco

    [blocco]
    ...]

</segment>

274.2   Figure e tabelle

Le figure interne al testo seguono la sorte di tutti gli altri elementi del genere, mentre le figure contenute nell'elemento figure possono spostarsi sulla superficie della pagina. In questo senso, conviene indicarle sempre a partire dalla prima colonna, anche quando si chiede espressamente che rimangano fisse nella posizione in cui si trovano nel sorgente. L'elemento figure è predisposto per contenere altri elementi, che però non è il caso di indicare con rientri. L'esempio seguente mostra la situazione comune in cui la figura è rappresentata dall'elemento image; in particolare merita attenzione la didascalia.

<figure id="f-esempio-1">
<fcaption>

    Figura <figureref>. Bla bla bla...

</fcaption>
<image imgfile="esempio-1" height="4cm">
</figure>

In effetti, la didascalia è contenuta in un elemento fcaption che costituisce un blocco di testo. In precedenza è stata descritta la regola per cui i blocchi di testo devono essere realizzati ponendo il marcatore iniziale e quello finale in aderenza al testo contenuto, reimpaginando il tutto in base all'incolonnamento. Tuttavia, quello che si vede nell'esempio è lo stile proposto, che vale quindi come eccezione nel caso delle didascalie di figure, tabelle e listati.

Per le tabelle valgono le stesse considerazioni in relazione alle didascalie, mentre si propone una struttura particolare per l'elenco degli elementi che compongono le varie righe.

<table id="t-alml-isolat1-2">
<tcaption>

    Tabella <tableref>. Entità <special special="name">ISOlat1</special>:
    <bibref>added latin 1</bibref>. Seconda parte.

</tcaption>
<tabular col="3">
<thead>
  <trow>SGML macro
<colsep>Risultato
<colsep>Descrizione in inglese
</trow>
</thead>
<tbody>
  <trow>&amp;ntilde;
<colsep>&ntilde;
<colsep>small n, tilde
</trow>
...
  <trow>&amp;yuml;
<colsep>&yuml;
<colsep>small y, dieresis or umlaut mark
</trow>
</tbody>
</tabular>
</table>

L'esempio mostra una situazione tipica. Si può osservare l'allineamento particolare del marcatore <trow> per avere il testo di tutte le celle della tabella allineato sulla stessa colonna del sorgente.

274.3   Sezioni marcate

Le sezioni marcate devono essere delimitate correttamente e quando queste sono annidate, si possono creare problemi nel riconoscere la fine di questa o quella sezione. Per evitare ambiguità, è bene segnalare la macro dell'entità parametrica relativa:

<[%nome_entità_parametrica;[

blocco_protetto

[blocco_protetto]
...

]]><!--%nome_entità_parametrica;-->

Quando una sezione marcata controlla una porzione di testo normale, è sufficiente che sia evidente l'ambito della sezione stessa. Per esempio:

<p>Bla bla bla <![%SENZACONTROLLO;[ciao ciao]]> bla bla bla...</p>