linuxdoc(1) LinuxDoc DTD SGML convertitore ad altri formati di uscita

SINTASSI

linuxdoc --backend=formato
--papersize=size --language=lang --charset=char --style=file --debug --define attributo=valore --include entity [opzioni-backend...] file(.sgml)

o (Uso vechio, obsoleto)
sgmlxxxx [opzioni-generiche...] [opzioni-backend...]   file(.sgml)

DESCRIZIONE

La suite linuxdoc e` una collezione di formatatori di testo che comprendono un file sorgente SGML di LinuxDoc DTD. Ogni formattatore (o "back-end") converte il file sorgente in una varieta` di formati di uscita, includendo HTML, TeX, DVI, PostScript, testo semplice, e il sorgente groff(1) nel formato delle pagine di manuale. La suite linuxdoc e` fornita di retro compatibilita`, dato che ci sono ancora molti documenti utili scritti in sorgente sgml di LinuxDoc DTD.

Il liguaggio di macatuta accettato da questi formattatori e` descritto nella Linuxdoc-ToolsGuida dell'Utente. Ci sono delle varianti di una document type definition SGML sviluppate originariamente da Matt Welsh per la documentazione di Linux.

OPZIONI-GENERICHE

La maggior parte delle opzioni da riga di comando sono accettate da tutti i back-end. Alcuni back-end hanno opzioni specifiche per controllare la loro resa al proprio particolare formato di uscita. Queste sono le opzioni piu` comuni:
--backend=formato, -B
Imposta il back-end per un formato specifico. Il formato predefinito e` nessuno dei formati attuali, ma solo l'uscita dell'uso di questa suites. I formati disponibili sono: html, info, latex, lyx, rtf, txt, check.
--papersize=size, -p
Imposta le dimensioni della pagina. Il formato prdefinito e` ``a4'' (pagina Europea 297x210mm). Si puo` specificare amche il formato ``letter''.
--language=lang, -l
Specifica la lingua del documento (questo puo` cambiare dipendentemente da quale file di stile e` usato da un back-end per la formattazione). La lingua predefinita e` l'Inglese. Per vedere la lista dei codici di lingua validi eseguire un comando LinuxDoc-tools senza argomenti.
--charset=chars, -c
Specifica la codifica del carattere di uscita. La codifica predefinita a ``ascii'' seleziona il set di caratteri ASCII; si puo` specificare "latin" per specificare il set di caratteri ISO 8859-1 (Latin-1). Inoltre, ``nippon'' e ``euc-kr'' sono richiesti per gestire le rispettive codifiche euc-jp e euc-kr del file sgml.
--style=file, -S
Include un DTD (Document Type Definition) ausiliario da /usr/share/linuxdoc-tools/dtd.
--tabsize=n, -t
Imposta gli spazi di tabulazione (tab) assunti per la generazione del documento di uscita. Il valore perdefinito degli spazi di tabulazione e` 8.
--debug, -d
Non elimina i file intermedi (come i file .TeX generati sul passaggio a un .dvi, o i file .man eliminati sul passaggio al testo semplice).
--define, -D
Passa la coppia attributo/valore per essere corrisposta su i condizionali "if" e "unless". Vedere la Guida dell'Utente per una discussione estesa di di questa caratteristica. Questa condizionalizzazione e` gestita dal comando sgmlpre. Vedere la pagina di manuale di sgmlpre(1) cosi` come la Guida dell'Utente.
--include, -i
Passa una opzione -i al comando nsgmls(1). Questo puo` essere usato per l'inclusione di condizionali. Vedere la pagina di manuale di nsgmls(1) per i dettagli.
--pass, -P
Passa una stringa di opzioni al back-end. L'esatta semantica di queste opzioni e` dipendente dal back-end e dovrebbe essere spiegata nella pagina di manuale relativa a ogni back-end.
file
Il file sorgente SGML, chiamato file o file.sgml.

L'esecuzione di un back-end senza alcun argomento produrra` una lista di tutte le sue opzioni (Il messaggio di errore riguardo a "no filenames given" in questo caso puo` essere sicuramente ignorato). I back-end disponibili includono (i nomi tra parentesi sono la forma vecchia & osoleta):

linuxdoc -B html (sgml2html)
traduce in HTML
linuxdoc -B info (sgml2info)
traduce in GNU info
linuxdoc -B lyx (sgml2lyx)
traduce in macro di Lyx
linuxdoc -B latex (sgml2latex)
traduce in LaTeX 2e
linuxdoc -B rtf (sgml2rtf)
traduce in Microsoft Rich Text Format
linuxdoc -B txt (sgml2txt)
traduce in testo semplice o nel markup delle pagine di manuale Unix

C'e` anche linuxdoc-Bcheck
 (sgmlcheck) uno strumento disponibile per verificare la sintassi LinuxDoc DTD SGML dei documenti sorgenti attualmente senza generare una versione tradotta.

DRIVER DI BACKEND

Di seguito c'e` la descrizione per ogni driver di backend:


 ****************************************************

linuxdoc -B html (sgml2html) converte un file sorgente SGML di LinuxDoc DTD in file HTML di uscita. L'uscita apparirà nel file di livello piu` alto file.html e file-n.html per ogni sezione (azione predefinita, ma puo` essere cambiata con un'opzione), dove file e` il nome del file sorgente SGML e n e` il nome della sezione.

La coppia attributo/valore "output=html" e` impostata per i condizionali.

linuxdoc -B html accetta le seguenti opzioni: [--split 0|1|2 ] [--dosnames] [--imagebuttons] [--toc 0|1|2 ]

Il significato di queste opzioni e`:

--split, -s
A quale livello dividere i documenti sorgenti. 0 = non dividere, 1 = dividere attraverso le sezioni principali, 2 = dividere attraverso le sottosezioni.
--toc, -T
A quale livello generare la toc (table of contents).
  0 = non generare la toc,
  1 = include le sezioni principali(/capitoli/parti),
  2 = include le sottosezioni.
--dosnames, -h
Usa ".htm" invece di ".html" come estensione dei file
--imagebuttons, -I
Usa le icone delle immagini "next" (successivo), "previous" (precedente), e "contents" (contenuti) incluse nella directory /usr/share/linuxdoc-tools come pulsanti di navigazione.
--footer, -F
Usa il file specificato come il footer in ogni file html ottenuto. Il footer predefinito e` solo il semplice

 </BODY>\n </HTML>\n
--header, -H
Usa il file specificato come la parte piu` alta dell'intestazione in ogni file html ottenuto. Notare che questo non e` la parte completa dell'intestazione. (per esempio, il titolo e i links (next,previous,contents) non sono tenuti nell'intestazione predefinita. L'intestazione predefinita e`

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\n
 <HTML>\n <HEAD>\n


 ****************************************************

linuxdoc -B info (sgml2info) converte un file sorgente SGML di LinuxDoc DTD al formato info GNU. L'uscita apparira` nel file.info dove file e` il nome del file sorgente SGML.

La coppia attributo/valore "output=info" e` impostata per i condizionali.

linuxdoc -B info non ha opzioni specifiche di backend.


 ****************************************************

linuxdoc -B latex (sgml2latex) converte un file sorgente SGML di LinuxDoc DTD in un file di uscita LaTeX, usando l'analizzatore nsgmls(1) o onsgmls(1), e il traduttore sgmlsasp(1). Usando l'uscita LaTeX, e il formattatore di testo latex(1), si puo` creare un'uscita DVI, e un'uscita PostScript usando il convertitore dvips(1). L'uscita apparira` nel file.tex per l'uscita LaTeX, file.dvi per l'uscita DVI, o file.ps per l'uscita PostScript, dove file e` il nome del file sorgente SGML.

Usando l'uscita LaTeX, e il formattatore di testo pdflatex(1), poi si puo` creare un file di uscita PDF piacevole, adatto per essere visualizzato con visualizzatori di PDF come xpdf(1), acroread(1) o ghostview(1).

La coppia attributo/valore "output=latex2e" e` impostata per i condizionali.

linuxdoc -B latex accetta le seguenti opzioni specifiche di backend: [--output=tex|dvi|ps|pdf] [--bibtex] [--makeindex] [--pagenumber=n] --quick [--latex=latex|hlatexp|platex|jlatex] [--dvips=dvips|dvi2ps]

Il significato di queste opzioni e`:

--output=fmt, -o
Specifica il formato di uscita voluto. Il formato specificato fmt puo` essere ``tex'', ``dvi'', ``ps'', o ``pdf''.

Nota: Questa versione non sovrascrive/rimuove i file intermedi: il file per l'uscita dvi, o i file per l'uscita ps. Questo comportamento e` differente dall'SGML-Tools 1.0.9 originale, cosi` si e` avvertiti.

--bibtex, -b
Elabora il file TeX generato con bibtex(1).
--makeindex, -m
Genera un file index TeX adatto per l'elaborazione con makeindex(1) dai tag <idx> e <cdx> presenti nel sorgente SGML.
--pagenumber, -n
Imposta il numero della pagina iniziale nel file di uscita DVI o PS.
--quick, -q
Fa solamente un passaggio della formattazione. Spesso questo non e` sufficiente per produrre un'uscita finale (dovuta ai riferimenti, ecc.) ma e` utile per mostrare gli errori di TeX e i problemi di giustificazione.
--pass, -P
L'argomento dell'opzione pass e` inserito subito dopo il preambolo di LaTeX generato dal tag del tipo di documento. Specifica il formato di uscita voluto. Il formato specificato fmt puo` essere ``tex'', ``dvi'', ``ps'', o ``pdf''.
--latex=comando_latex_alternativo, -x
Questa opzione correntemente e` per il coreano e il giapponese. Il comando_latex_alternativo puo` essere ``latex'' (predefinito), ``hlatexp'' (per il coreano), ``platex'' o ``jlatex'' (per il giapponese). Questa opzione puo` essere usata per ottenere un documento coreano usando HLaTeXp, o per ottenere un documento giapponese usando pLaTeX/jLaTeX. Altrimenti, HLaTeX dovrebbe essere installato per ottenere un documento coreano. In altre parole, un documento giapponese puo` essere ottenuto con jLaTeX
 (che e` il predefinito quando e` specificato ``-c nippon''), cosi` se si  ha gia` installato jLaTeX, non e` necessario installare pLaTeX.
--dvips=comando_dvips_alternativo, -s
Questa opzione e` correntemente per il giapponese. Il comando_dvips_alternativo puo` essere ``dvips'' o ``dvi2ps''. Se non si conosce questo, allora questo non e' necessario.


 ****************************************************

linuxdoc -B lyx (sgml2lyx) converte un file sorgente SGML di LinuxDoc DTD a un file di uscita LyX. L'uscita apparira` nel file.lyx dove file e` il nome del file sorgente SGML.

La coppia attributo/valore "output=lyx" e` impostata per i condizionali.

linuxdoc -B lyx non ha opzioni specifiche di backend.


 ****************************************************

linuxdoc -B rtf (sgml2rtf) converte un file sorgente SGML di LinuxDoc DTD a RTF, il Rich Text Format usato dal sistema di aiuto di Microsoft Windows. L'uscita apparira` nel file di piu` alto livello file.rtf e file-n.rtf per ogni sezione, dove file e` il nome del file sorgente SGML. L'uscita RTF e` adatta alla compilazione con il Compilatore dell'Help di Windows Help (hc31.exe).

La coppia attributo/valore "output=rtf" e` impostata per i condizionali.

linuxdoc -B rtf accetta [--twosplit] come un'opzione specifica di backend. Il significato di questa opzione e` il seguente:

--twosplit, -2
Divide i file sia a n. seczioni che a n.m. sottosezioni


 ****************************************************

linuxdoc -B txt (sgml2txt) converte un file sorgente SGML di LinuxDoc DTD a file di uscita ASCII, ISO-8859-1, o EUC-JP. L'uscita apparira` nel file.txt dove file e` il nome del file sorgente SGML.

La coppia attributo/valore "output=txt" e` impostata per i condizionali.

linuxdoc -B txt accetta le seguenti opzioni di backend: [--manpage] [--filter] [--blanks=n]

Il significato di queste opzioni e`:

--manpage, -m
Produce in uscita un file sorgente di groff, adatto per la formattazione con groff -man per le pagine di manuale
--filter, -f
Rimuove gli backspace-overstrikes dai file intermediari generati da groff(1).
--pass, -P
L'argomento dell'opzione pass e` aggiunto alle opzioni della riga di comando gestite da groff(1).
--blanks=n, -b
Imposta il limite delle linee bianche consecutive per la generazione del documento di uscita. Il limite predefinito e` 3. Se e` specificato 0 (zero), il risultato avra` molte linee bianche consecutive.


 ****************************************************

linuxdoc -B check (sgmlcheck) esegue un analizzatore SGML sul documento sorgente specificato. Ogni errore e` riportato sullo standard output. Nessuna versione formattata del sorgente e` prodotta.

Notare che linuxdoc -B check pre-elabora il sorgente SGML di LinuxDoc DTD, facendo la condizionalizzazione descritta da ogni tag <#if></#if> e <#unless></#unless>. I documenti sorgenti che contengono questi tag confonderanno un analizzatore SGML standalone. linuxdoc -B check non ha opzioni specifiche di backend.
 ****************************************************

FILE

Sono usati molti file ed eseguibili nelle directory /usr/share/linuxdoc-tools e /usr/bin.

BUG

Potrebbe essercene qualcuno. Ci si senta liberi di inviare il proprio report al corrente manutentore.

MANUTENTORE

Questa pagina di manuale e` stata mantenuta da Cees de Groot <[email protected]> in SGML-Tools (v1). Attualmente e` mantenuta da Taketoshi Sano <[email protected]> per Linuxdoc-Tools. Traduzione ed adattamenti a cura di Hugh Hartmann <[email protected]>. Revisione a cura di Beatrice Torracca <[email protected]>.