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.

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]>.