TXT2TAGS

Maggio, 2005

%!target: man
%!encoding: UTF-8

%!postproc(man): ' \(#\w+\)' ''

%!options(html): --mask-email --toc
%!postproc(html): <HEAD> '<HEAD>\n<STYLE>body{margin:3em;} pre{background:#ffc;}</STYLE>'


= NOME =

txt2tags - utility per la formattazione e la conversione del testo

= SINOPSI =

**txt2tags** [//OPTION//]... [//FILE//]...

= DESCRIZIONE =

**txt2tags** è un'utility GPL scritta in Python per la formattazione e la
conversione del testo che genera documenti //HTML//, //XHTML//, //SGML//,
//LaTeX//, //Lout//, //Man Page//, //MoinMoin//, //MagicPoint// e
//PageMaker// da un singolo file di testo contenente un markup minimale.

L'utente deve soltanto conoscere i pochi simboli **txt2tags**,
e scrivere semplici file di testo. Il programma fa tutto il lavoro sporco,
aggiungendo i simboli necessari e gestendo i problemi di conversione.

Uno stesso file può essere convertito in tutti i formati di destinazione, senza
ulteriori modifiche. Questo è lo scopo di **txt2tags**: MONO sorgente,
MULTI destinazione.

Visita l'home page //""http://txt2tags.org""//.


= OPZIONI =

:  **-C**, **--config-file**
legge le configurazioni da un file esterno (come %!includeconf)

:      **--css-sugar**
inserisce tag compatibili con CSS, per HTML e XHTML

:      **--css-inside**
inserisce il contenuto del file CSS nell'intestazione HTML/XHTML

:      **--dump-config**
visualizza tutte le configurazioni trovate ed esce

:      **--dump-source**
visualizza il documento sorgente, espandendo le inclusioni

:      **--encoding**
imposta la codifica del file di destinazione (utf-8, iso-8859-1, etc)

:      **--gui**
avvia l'interfaccia grafica Tk

:  **-h**, **--help**
visualizza le informazioni di aiuto ed esce

:  **-H**, **--no-headers**
sopprime intestazione, titoli e pié di pagina

:      **--headers**
mostra intestazioni, titoli e pié di pagina (predefinito SI)

:  **-i**, **--infile**=//FILE//
setta FILE come file sorgente ('-' per STDIN)

:      **--mask-email**
nasconde l'email agli spam robot. x@y.z diventa <x (a) y z>

:  **-n**, **--enum-title**
enumera le righe di titolo come 1, 1.1, 1.1.1, etc

:      **--no-dump-config**
disattiva la visualizzazione delle configurazioni

:      **--no-dump-source**
disattiva la visualizzazione del documento sorgente

:      **--no-encoding**
cancella l'impostazione della codifica

:      **--no-enum-title**
disattiva la numerazione automatica dei titoli

:      **--no-infile**
cancella le precedenti impostazioni del nome del file sorgente

:      **--no-mask-email**
mostra le email, disattivando l'opzione --mask-email

:      **--no-outfile**
cancella le precedenti impostazioni del nome del file destinazione

:      **--no-quiet**
mostra i messaggi, disattivando l'opzione --quiet

:      **--no-rc**
non legge il file di configurazione utente ~/.txt2tagsrc

:      **--no-style**
cancella le impostazioni dello stile

:      **--no-toc**
non aggiunge l'indice al documento di destinazione

:      **--no-toc-only**
disattiva l'opzione --toc-only

:  **-o**, **--outfile**=//FILE//
setta FILE come file destinazione ('-' per STDOUT)

:  **-q**, **--quiet**
sopprime tutti i messaggi (esclusi gli errori)

:      **--rc**
legge il file di configurazione utente ~/.txt2tagsrc (predefinito SI)

:      **--style**=//FILE//
usa FILE come stile del documento (come HTML CSS)

: **-t**, **--target**
setta il formato del documento di destinazione. formati supportati:
html, xhtml, sgml, tex, lout, man, mgp, moin, pm6, txt

:      **--toc**
aggiunge l'indice al documento di destinazione

:      **--toc-level**=//N//
setta la profondità massima dell'indice ad N

:      **--toc-only**
stampa l'indice del documento ed esce

:  **-v**, **--verbose**
stampa messaggi informativi durante la conversione

:  **-V**, **--version**
visualizza la versione del programma ed esce


Come opzione predefinita, il documento di destinazione convertito è salvato in 'file.<type>'.
Usa --outfile per forzare un nome del file di destinazione.
Se il file sorgente è '-', legge da STDIN.
Se il file di destinazione è '-', indirizza l'output su STDOUT.


=  STRUTTURA =

Il file sorgente Txt2tags può avere tre aree:

: **Intestazione**
Le prime tre linee. Sono usate per l'identificazione del documento.
Se non necessiti dell'intestazione, devi lasciare vuota la prima riga o utilizzare
l'opzione ``no-header``.

: **Configurazioni**
Inizia dopo l'area di Intestazione (alla quarta riga o alla seconda riga). Tutti i
settaggi hanno il formato ""%!keyword: value"".
I settaggi possono anche essere importati da un file di configurazione o dalla
riga di comando.

: **Corpo**
Il documento sorgente vero e proprio! Questa è l'unica area richiesta per avere
un file txt2tags valido ed inizia alla prima linea di testo valida (non commento
o configurazione) dopo l'area di Intestazione.


= SETTAGGI =

La conversione di un file sorgente può essere personalizzata in due diversi
modi. Le configurazione esterne sono prese dal file ``~/.txt2tagsrc`` o da un
altro file scelto dall'utente. La configurazione interna è fatta con i settaggi
nell'area di Configurazione. Entrambe le configurazioni usano la stessa sintassi:

: **%!target:**
definisce il formato di destinazione principale

: **%!options(target):**
definisce le opzioni per ogni formato di destinazione

: **%!include: file.t2t**
inserisce un file txt2tags nel documento

: **%!include: ""``file.txt``""**
inserisce un file di testo nel documento, preservando spazi e formattazione

: **%!include: ''file.html''**
inserisce un file nel documento senza alcuna elaborazione da parte di txt2tags

: **%!style:**
definisce un file CSS (Cascading Style Sheets) per i formati di destinazione
XHTML and HTML o per caricare moduli \usepackage nel formato di destinazione
TEX

: **%!encoding:**
imposta la codifica (come iso-8859-1) per la traduzione i18n

: **%!includeconf:**
include una configurazione da un file esterno

: **%!guicolors:**
imposta i colori per l'interfaccia grafica Tk/Tcl

: **%!preproc:**
i tuoi filtri personalizzati (macro) che verranno elaborati **PRIMA**
dell'elaborazione del documento

: **%!postproc:**
i tuoi filtri personalizzati (macro) che verranno elaborati **DOPO**
l'elaborazione del documento



== REGOLE DEI SETTAGGI ==

 - I settaggi sono validi soltanto nell'area di Configurazione, e sono considerati
   semplici commenti se sono trovati nel Corpo del documento. Eccetto include,
   che è un comando valido all'interno del Corpo del documento.

 - Se la stesso settaggio compare più di una volta nell'area di Configurazione,
   verrà usato solo l'ultimo trovato. Fanno eccezione: options, preproc
   e postproc, che sono settaggi cumulativi.

 - Una riga di settaggio con un settaggio invalido verrà considerato una semplice
   riga di commento.

 - I settaggi nell'area di Configurazione hanno la precedenza sul file txt2tagsrc,
   ma non sulle opzioni da riga di comando.


= SINTASSI =

Nel documento sorgente (il file contenente solo testo) è usata una sintassi molto
semplice per identificare la struttura e la formattazione.
Ecco la lista completa della sintassi:

== Base ==
```
Intestazione        Le prime tre righe del file sorgente
Titolo              = testo =
Titolo numerato     + testo +
Paragrafo           testo
```

== Formattazione ==
```
Grassetto           **testo**
Italico             //testo//
Sottolineato        __testo__
Monospazio          ``testo``
```

== Blocchi di testo ==
```
Citazione           <TAB>testo
Lista               - testo
Lista numerata      + testo
Lista di definiz.   : testo
Linea 'letterale'   ``` testo
Area 'letterale'    ```<RitornoACapo> linee <RitornoACapo>```
Linea 'grezza'      """ testo
Area 'grezza'       """<RitornoACapo> linee <RitornoACapo>"""
Tabella             | cella1 | cella2 | cella3...
```

== Altro ==
```
Linea separatrice   -----------------------...
Linea più spessa    =======================...
Colleg.ipertest.    [etichetta url]
Immagine            [nomefile.jpg]
Testo 'grezzo'      ""testo""
Commento            % commento
```

Per una descrizione dettagliata della sintassi leggi la Guida
dell'Utente Txt2tags (nella directory dei documenti).


= ESEMPI =

Supponendo di avere scritto il file ``file.t2t``, procediamo con
la conversione.

: **Conversione in HTML, salvando in file.html**
``$ txt2tags -t html file.t2t``

: **Lo stesso, usando il reindirizzamento**
``$ txt2tags -t html -o - file.t2t > file.html``

: **Includendo l'indice**
``$ txt2tags -t html --toc file.t2t``

: **Includendo l'indice ed i titoli numerati**
``$ txt2tags -t html --toc --enum-title file.t2t``

: **Visualizzando solo l'indice**
``$ txt2tags --toc-only file.t2t``

: **Test su un'unica riga, leggendo il testo da STDIN**
``$ (echo ; echo "**bold**") | txt2tags -t html -H -``


= MACRO =


: ""%%date""
Permette di includere la data corrente, nel formato AAAAMMGG.
Formattazione opzionale si può ottenere usando la sintassi
""%%date(format-string)"".

: ""%%infile""
Usato per ottenere informazioni circa il file sorgente. Formattazione
opzionale si può ottenere usando la sintassi
""%%infile(format-string)"".

Utile per collegamenti nel pié di pagina come ""[Vedi sorgente %%infile]"",
in quanto se il nome del file sorgente viene cambiato, esso verrà aggiornato
nel documento convertito.

: ""%%mtime""

Restituisce informazioni circa la data e l'ora di modifica del documento
sorgente. Usa la stessa formattazione della macro ""%%date"".

: ""%%outfile""
Usato per ottenere informazioni circa il file convertito. Formattazione
opzionale si può ottenere usando la sintassi ""%%outfile(format-string)"".

Utile per riferirsi al documento corrente, come "Questo è il file %%outfile";
se il nome del file convertito viene cambiato, esso verrà aggiornato.

: ""%%toc""
La macro ""%%toc"" specifica dove verrà inserito l'indice del documento.
Esso può essere inserito in qualunque punto all'interno del documento.

NOTA: ""%%toc"" sarà convertito nell'indice solo se si utilizza l'opzione ""--toc"".


= ALTRE INFORMAZIONI UTILI (*) =

```
(*) Questa sezione non è presente nella versione originale
    inglese, ma è stata aggiunta dal traduttore nella versione italiana
    (ispirato dalla sezione 'TRUCS' della versione francese).
    
    This section is not present in the original english version, but it
    has been added by the italian translator (inspired by the 'TRUCS'
    section of the french version).
```

Elenchiamo di seguito alcune caratteristiche che rendono txt2tags
un'eccellente utility per scrivere i nostri documenti.


== COLLEGAMENTI IPERTESTUALI NEL DOCUMENTO ==

I titoli possono essere usati come destinazione di collegamenti ipertestuali,
per essere raggiunti direttamente (se il formato lo consente) come se fossero
collegamenti a pagine web.

Definizione del collegamento (all'interno del titolo):

```
  Titolo            = testo =[NomeCollegamento]
  Titolo numerato   + testo +[NomeCollegamento]
```
  

Richiamo del collegamento (all'interno di un paragrafo di testo):

```
  testo testo [DescrizioneCollegamento #NomeCollegamento] testo testo
```


== FILE MULTIPLI ==

txt2tags può elaborare più file contemporaneamente, come segue:

   txt2tags *.t2t 


= AUTORE =

Scritto e mantenuto da Aurelio Jargas <verde@aurelio.net>

Questa pagina di manuale è stata scritta da Jose Inacio Coelho <jic@technologist.com>
come file di testo, e convertita nel formato man da **txt2tags**!

Tradotto da Spinucci Stefano <virgo977@tin.it>


= COPYRIGHT =

Copyright (C) 2001, 2002, 2003, 2004, 2005 Aurelio Jargas

This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
