Elementi ed attributi non permessi

Supportato, non supportato e non permesso

Non tutti gli elementi (tag) ed attributi che funzionano con Publican sono supportati. Nello specifico, non tutti i tag sono stati testati riguardo agli effetti sulla presentazione di un documento in formato HTML o PDF.

Publican funziona con quasi tutti gli elementi e relativi attributi di DocBook 4.5, la maggior parte dei quali sono supportati. Gli elementi ed attributi supportati sono quelli la cui presentazione in HTML e PDF di Publican sono stati testati e conservano un livello di qualità accettabile.

Altri elementi ed attributi non riconosciuti dannosi o ridondanti, ma che non sono stati testati per qualità sono non supportati. Se il contenuto all'interno di un particolare tag DocBook non viene visualizzato correttamente in un documento HTML o PDF, il problema può derivare da una mancanza di test sulla logica di trasformazione del relativo tag. Provare a ricreare il documento e controllare l'output generato da Publican durante la creazione del documento. Publican presenta avvisi sui tag non supportati man mano che vengono elaborati i file XML.

Infine, un ristretto gruppo di elementi ed attributi sono non permessi. Questi elementi ed attributi sono elencati in basso, accompagnati da una spiegazione del motivo del divieto.

Usare il comando publican print_known per visualizzare l'elenco dei tag supportati da Publican, ed il comando publican print_banned per visualizzare l'elenco dei tag non permessi in Publican.

A.1. Elementi non permessi

<caution>, <tip>

DocBook XML supporta cinque tipi di avvisi per vari di livelli di severità: <tip>, <note>, <important>, <caution> e <warning>. Complessivamente, essi rappresentano un insieme di distinzioni a grana molto fine. E' improbabile che queste sottili distinzioni possano applicarsi consistenemente in un documento, in specie quando un documento è redatto o mantenuto da più persone. Inoltre, questo livello di granularità può sembrare insignificante ai lettori. Per progetto, Publican disabilita gli elementi <tip> e <caution>, essendo gli elementi più ridondanti del gruppo.

Usare <note> invece di <tip>, ed usare <important> o <warning> invece di <caution>. Alcuni criteri, in base ai quali selezionare i livelli di severità sono indicati nella sezione ‘Convenzioni del Documento’ della Prefazione dei libri prodotti con il brand predefinito di Publican.

<entrytbl>

Publican dipende da un'applicazione esterna, FOP, per rendere documenti PDF. Al momento, FOP non supporta l'annidamento delle tabelle (nested tables), quindi ogni tentativo di creare file PDF da documenti Publican contenenti tabelle annidate fallisce.

L'annidamento delle tabelle è perciò vietato almeno fino a quando non supportato in FOP. Se si prevede di includere una tale tabella, si riconsideri di ristrutturare la struttura dei dati

<glossdiv>, <glosslist>

Questo tag presenta i termini nei glossari in ordine alfabetico; tuttavia, i termini vengono ordinati secondo la lingua originale dell'XML, a prescindere se i termini siano tradotti in altre lingue. Per esempio, un glossario prodotto con <glossdiv> che in lingua inglese appare come:

A: Apple — an apple is…
G: Grapes — grapes are…
O: Orange — an orange is…
P: Peach — a peach is…

in italiano appare come:

A: Mela — una mela è…
G: Uva — l'uva è…
O: Arancia — un'arancia è…
P: Pera — la pera è…

Quindi tradotto in una lingua che non condivide lo stesso sistema di scrittura della lingua originale in cui è redatto l'XML, il risultato del tag è privo di senso.

<inlinegraphic>

Questo elemento presenta le informazioni contenute in un oggetto grafico, privo di una opzione per una presentazione alternativa in modalità testuale. Perciò questo tag limita l'accesso alle informazioni alle persone con ridotte cpacità visive. Negli Stati in cui vige una legislazione che garantisce l'accessibilità ai contenuti elettronci alle persone con ridotte capacità visive, i documenti contenenti questo tag quindi non soddisfano queste richieste. La Section 508 del Rehabilitation Act of 1973^[4] è un esempio di tali richieste predisposte alle Agenzie Federali degli Stati Uniti d'America.

Notare che il tag <inlinegraphic> non è valido in DocBook versione 5.

<link>

Il tag <link> offre un generico collegamento ipertestuale e quindi nulla di più dei tag <xref> e <ulink>, rispettivamente, per collegamenti interni ed esterni. Quidni il tag <link> è disabilitato per ridondanza.

<olink>

Il tag <olink> offre riferimenti tra documenti XML. Per usare il tag <olink> per riferimenti ai documenti esterni facenti parte della stessa libreria di file XML, occorre fornire l'URL del documento da linkare. In ambienti che usano il tag <olink>, questi URL possono essere forniti sia con entità XML sia con script server-side. Publican produce documenti di vasta diffusione in cui gli URL sono sempre indispensabili per riferimenti incrociati. Quindi, il tag <olink> non offre alcun vantaggio sul tag <ulink> e perciò per ridondanza, è disabilitato.

A.2. Attributi non permessi

<[element] xreflabel="[ogni_altra_stringa]">

La presenza di un attributo <xreflabel> riduce l'usabilità delle versioni stampate di un libro. Inoltre, i valori dell'attributo non sono visibili ai traduttori, e perciò non sono traducubili.

Per esempio, il seguente pezzo:

<chapter id="ch03" xreflabel="Chapter Three">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

…see <xref linkend="ch03"> for details.

durante la trasformazione in HTML del file XML, il tag <xref> diventa un tag anchor, come indicato di seguito:

…see <a href="#ch03">Chapter Three</a> for details.

Il testo contenuto nel tag anchor coincide con quello nell'attributo <xreflabel>. In questo caso, ciò vuol dire che i lettori delle versioni stampate hanno una perdita di informazione.

Per evitare questo problema si può far coincidere il valore dell'attributo <xreflabel> con il testo contenuto tra i tag <title></title>. Tuttavia questa duplicazione aumenta il rischio di errori di battitura, senza in effetti alcun miglioramento. E riduce anche la quantità di informazione presentata ai lettori delle copie stampate.

Il seguente XML:

<chapter id="ch03" xreflabel="The Secret to Eternal Life">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

…see >xref linkend="ch03"> for details.

viene trasformato in tag anchor HTML come segue:

…see <a href="#ch03">The Secret to Eternal Life</a> for details.

Ciò non è così informativo come il testo presentato senza usare l'attributo <xreflabel>. Il seguente:

<chapter id="ch03">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]		

…see <xref linkend="ch03"> for details.

trasforma l'elemento <xref> come segue in formato HTML:

…see <a href="#ch03">Chapter 3: The Secret to Eternal Life</a> for details.

Comunque, ancora più importanti, sono i problemi di traduzione causati dal tag <xreflabel>. I valori degli attributi non sono visibili ai traduttori. Di conseguenza, non possono essere tradotti. Si consideri di nuovo il secondo esempio, di cui sopra:

<chapter id="ch03" xreflabel="The Secret to Eternal Life">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]		

…see <xref linkend="ch03"> for details.

In inglese, <xref> è ancora trasformato in un tag anchor come segue:

…see <a href="#ch03">The Secret to Eternal Life</a> for details.

Mentre i lettori della versione in lingua tedesca, visualizzeranno il seguente HTML:

…Sehen Sie <a href="#ch03">The Secret to Eternal Life</a> für Details.

Rimuovendo l'attributo <xreflabel>, i tag del titolo e del capitolo, appaiono propriamente tradotti al lettore. Cioè il segente pezzo:

<chapter id="ch03">
	<title>The Secret to Eternal Life</title>
	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]		

…see <xref linkend="ch03"> for details.

per una traduzione in lingua tedesca, viene visualizzato come:

…Sehen Sie <a href="#ch03">Kapitel 3: Das Geheimnis des ewigen Lebens</a> für Details.

E ciò, senza meravigliarsi più di tanto, è ciò che si vuole ottenre!

Quindi, per quanto fin quì detto, l'attributo xreflabel è vietato.

<[element] endterm="[any_string_here]">

L'attributo endterm permette di presentare il testo relativo all'ipertesto con un nome diverso dalla sezione o capitolo cui punta il collegamento. E ciò riduce l'usabilità della versione stampata del documento e genera difficoltà anche ai traduttori.

Il testo presentato in un elemento (come un <xref>), contenente l'attributo endterm è ricavato dal tag <titleabbrev> nel capitolo o sezione target. Sebbene il contenuto del tag <titleabbrev> sia traducubile nei file PO del documento, esso viene di fatto rimosso dal contesto del tag <xref>. L'assenza di questo contesto rende praticamente impossibile la traduzione di articoli e preposizioni, preservando genere e numero.

Per esempio, il seguente pezzo:

<chapter id="The_Secret">
	<title>The Secret to Eternal Life</title>
	<titleabbrev id="final">the final chapter</titleabbrev>

	<para>The secret to eternal life is…</para>
</chapter>

[more deathless prose here]     

The solution is in <xref linkend="The_Secret" endterm="final"/>.

Come si vede, il testo che precede il tag <xref> presente nella versione inglese del documento è:

The solution is in the final chapter.

Un traduttore vede il tag <titleabbrev> nel file PO come:

#. Tag: titleabbrev
#, no-c-format
msgid "the final chapter"
msgstr ""

e vede il testo contenuto in <xref> in qualche altra parte del file PO (o, addirittura in un PO completamente diverso), come:

#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr ""

Il traduttore non ha idea di come verrà sostituito il tag <xref linkend="The_Secret" endterm="final"/> durante la creazione del documento, per cui una traduzione in italiano potrebbe leggersi come:

#. Tag: para
#, no-c-format
msgid "The solution is in <xref linkend="The_Secret" endterm="final"/>."
msgstr "La soluzione è in <xref linkend="The_Secret" endterm="final"/>."

Notare la preposizione in.

Se il traduttore di lingua italiana traduce the final chapter in l'ultimo capitolo, il documento risultante si leggerebbe come:

La soluzione è in l'ultimo capitolo.

Il risultato è comprensibile, ma poco elegante, per l'assenza di combinazione tra preposizione ed articolo. Una traduzione più elegante sarebbe stata:

La soluzione è nell'ultimo capitolo.

Senza conoscere il testo che compare al posto di <xref linkend="The_Secret" endterm="final"/>, il traduttore in italiano non sa se usare la preposizione in invariata, o una delle sette possibili combinazioni con l'articolo determinativo: nel, nei, nello, nell', negli, nella o nelle.

Inoltre, notare che la combinazione della preposizione con l'articolo pone anche una problema se inserire la preposizione articolata nel tag <xref> o nel tag <titleabbrev>. E comunque qualunque sia la soluzione scelta dal traduttore, ulteriori problemi si verificano quando l'endterm è presente in altri contesti grammaticali, poichè sarebbe richiesta un'altra preposizione articolata.

A causa di queste difficoltà, in fase di traduzione di endterm, Publican non permette l'uso di questo attributo.

^[4] Fare riferimento a http://www.section508.gov/