successivo precedente inizio fine indice generale aiuto indice analitico volume parte TXT HTML PDF pdf gdoc P4

Sgmltexi: installazione e utilizzo

Sgmltexi (1) è un DTD e un sistema frontale per la composizione in Texinfo a partire da un formato SGML. L'idea alla base di Sgmltexi è quella di avere la possibilità di scrivere un documento Texinfo attraverso la semplificazione e la guida che può dare un sistema SGML.

All'interno di Sgmltexi, la gestione dei nodi di Texinfo può avvenire in modo automatico e trasparente, generando un menù Info unico nel nodo Top. I nomi dei nodi, quando sono generati automaticamente, usano stringhe del tipo «cap 1», «app A»,...

Sgmltexi ha uno schema preciso: ci possono essere una o più introduzioni iniziali; nella parte centrale c'è un corpo che può essere scomposto in vario modo; ci possono essere delle appendici; al termine possono apparire degli indici analitici. Il corpo è organizzato in capitoli, che possono essere raggruppati in parti ed eventualmente anche in tomi. In tal modo, si possono gestire facilmente anche documenti di grandi dimensioni.

Sgmltexi è un progetto che non viene più sviluppato, in considerazione del fatto che la documentazione GNU tende a migrare verso Docbook, pur garantendo la compatibilità con Texinfo.

Installazione di Sgmltexi

Sgmltexi è composto da due eseguibili Perl: sgmltexi e sgmltexi-sp2texi. Questi due file devono essere collocati in una directory in cui possono essere avviati senza bisogno di indicare il percorso; in pratica in una directory elencata all'interno della variabile di ambiente PATH.

Evidentemente, è necessario l'interprete Perl; precisamente questi programmi cercano il file /usr/bin/perl. Se il proprio sistema operativo è organizzato diversamente, è necessario intervenire modificando la prima riga dei due eseguibili:

#!/usr/bin/perl
...

Sgmltexi si aspetta di trovare alcuni file:

Tutti questi file dovrebbero trovarsi esattamente dove previsto; in alternativa si devono realizzare almeno dei collegamenti per ricreare i percorsi stabiliti.

Gettext

I messaggi di Sgmltexi possono essere tradotti. Per installare i file PO già esistenti è necessario compilarli come nell'esempio seguente:

$ msgfmt -vvvv -o sgmltexi.mo it.po[Invio]

In questo esempio, il file it.po viene compilato generando il file sgmltexi.mo. Questo file può essere collocato in /usr/share/locale/it/LC_MESSAGES/, o in un'altra posizione analoga in base agli standard del proprio sistema operativo.

Se non è disponibile il modulo Perl-gettext, che serve a Sgmltexi per accedere alle traduzioni, è possibile eliminare il suo utilizzo e simulare la funzione di Gettext. In pratica si commentano le istruzioni seguenti:

# Non si vuole usare gettext.
#use POSIX;
#use Locale::gettext;
#setlocale (LC_MESSAGES, "");
#textdomain ("sgmltexi");

Inoltre, si tolgono i commenti dalla dichiarazione della funzione fittizia gettext(), come si vede qui:

sub gettext
{
    return $_[0];
}

Dipendenze

È il caso di riepilogare le dipendenze di Sgmltexi da altri applicativi:

Come si usa il programma frontale

Una volta preparato il sorgente in formato Sgmltexi, bisogna utilizzare il programma sgmltexi per controllare l'elaborazione SGML e gli altri applicativi di composizione di Texinfo.

Di solito, la cosa migliore per iniziare lo studio di un sistema di composizione, è partire da un esempio banale, funzionante, che consenta di apprendere l'uso elementare degli strumenti relativi.

<!DOCTYPE Sgmltexi PUBLIC "-//GNU//DTD Sgmltexi//EN">
<sgmltexi lang="it">
<head>
    <admin>
        <setfilename content="esempio.info">
        <settitle content="Esempio">
    </admin>
    <titlepage>
        <title>Esempio</title>
        <subtitle>Un esempio per un documento in formato Sgmltexi</subtitle>
        <abstract>
            <p>Questo è solo un esempio di un documento scritto
            utilizzando Sgmltexi.</p>
        </abstract>
        <author>Pinco Pallino &lt;ppinco@dinkel.brot.dg&gt;</author>
        <legal>
            <copyright>Copyright &copy; 2000 Pinco Pallino</copyright>
            <license>
                <p>Permission is granted to copy, distribute and/or
                modify this document under the terms of the GNU Free
                Documentation License, Version 1.1 or any later version
                published by the Free Software Foundation; with no
                Invariant Sections, with no Front-Cover Texts, and with
                no Back-Cover Texts. A copy of the license is included
                in the section entitled "GNU Free Documentation
                License".</p>
            </license>
        </legal>
    </titlepage>
    <contents>
</head>
<body>
<h1>Esempio generale</h1>

<p>Questo è l'esempio tipico di un capitolo di Sgmltexi...</p>

<p>Non c'è molto da scrivere in questo caso...</p>

</body>
</sgmltexi>

Supponendo di avere installato correttamente Sgmltexi (e anche Texinfo), supponendo inoltre che il file si chiami prova.sgml, si possono usare i comandi seguenti:

La sintassi di sgmltexi è quella che si vede nello schema seguente:

sgmltexi [opzioni] sorgente_sgml

In generale, è bene che il nome del file sorgente in formato Sgmltexi abbia l'estensione standard .sgml.

Opzione Descrizione 
--help
Mostra una guida sintetica e termina di funzionare. 
--version
Mostra le informazioni sulla versione e termina di funzionare. 
--force
Quando il contesto lo consente, forza le situazioni. Può essere utile in particolare per la composizione in formato Info e in formato HTML, per passare la stessa opzione al programma makeinfo. 
--number-sections
Numera le sezioni quando ciò non è previsto in modo normale. 
--clean
Elimina i file intermedi che non servono, abbinati al nome del sorgente. 
--verbose
Mostra più informazioni durante l'elaborazione. 
--input-encoding=codifica
Stabilisce la codifica del file in ingresso, tenendo conto che sono ammissibili solo le parole chiave ISO-8859-n, dove n va da 1 a 10. 
--sgml-include=entità_parametrica

--include=entità_parametrica
Assegna la parola chiave INCLUDE all'entità parametrica SGML indicata. Questo serve ad abilitare l'inclusione di porzioni di sorgente SGML che sono controllate in questo modo. 
--paper=formato_composizione
Serve a definire in qualche modo il formato finale stampato di composizione. Sono disponibili le parole chiave seguenti: letter, a4, a4wide, a4latex e small. 
--setchapternewpage={on\
  \|off|odd}
Definisce l'inizio dei capitoli nella composizione per la stampa, ignorando il marcatore <setchapternewpage content="..."> all'interno del sorgente del documento. 
--footnotestyle={end\
  \|separate}
Definisce la collocazione delle note a piè pagina, ignorando il marcatore <footnotestyle content="..."> all'interno del sorgente. 
--headings={on|off|single\
  \|double|singleafter\
  \|doubleafter}
Attiva o disattiva le intestazioni, specificando eventualmente l'uso di intestazioni uguali o distinte. Questa opzione fa ignorare il marcatore <headings content="..."> all'interno del sorgente del documento. 
--sgml-syntax

--sgml-check
Controlla la correttezza formale del sorgente SGML, mostrando gli errori trovati. 
--sp
Genera un risultato «post-SP», nel senso che restituisce soltanto quanto ottenuto dall'analizzatore SGML, a scopo diagnostico. 
--texi

--texinfo
Genera un sorgente Texinfo. 
--dvi
Compone generando un risultato in formato DVI. 
--ps

--postscript
Compone generando un formato in PostScript. 
--pdf
Compone generando un formato PDF. 
--info
Generate un risultato in formato Info. 
--text
Genera un risultato in formato testo puro. 
--html
Genera un risultato in formato HTML. 
--xml
Genera un risultato in formato XML di Texinfo. 
--docbook
Genera un risultato in formato XML Docbook.

Riferimenti

1) Sgmltexi   GNU GPL

«a2» 2013.11.11 --- Copyright © Daniele Giacomini -- appunti2@gmail.com http://informaticalibera.net