# Estendere &quantaplus;

Christopher
Hornbaker

    chrishornbaker@earthlink.net

Samuele
Kaplun

    kaplun@aliceposta.it

Traduzione del documento

# Estendere &quantaplus;

Questo capitolo descrive come personalizzare &quantaplus; per i tuoi particolari bisogni e come puoi aiutare &quantaplus; a diventare migliore.

## Pacchetto di Editing del Tipo di Documento (&DTEP;)

I Pacchetti di Editing del Tipo di Documento (&DTEP;) vengono utilizzati in &quantaplus; per aggiungere il supporto per il markup, i linguaggi di scripting e &CSS;. Permettono a &quantaplus; di fornire funzionalità quali l'auto-completamento e gli alberi di nodi. La loro semplicità e flessibilità sono quello che rende &quantaplus; un &IDE; veloce, amichevole agli sviluppatori web. Sono quello che rende &quantaplus; un ambiente semplice da usare e produttivo.

&DTEP; appartengono a due classi, Famiglia 1, che riguarda il markup e Famiglia 2 che riguarda lo scripting ed il &CSS;. &DTEP; sono costituiti da due parti, la Cartella dei Tag e le Barre degli strumenti. Le Cartelle dei Tag sono composte da due tipi di file, i file description.rc ed i file TagXML, che hanno l'estensione .tag. Le Barre degli strumenti sono barre di pulsanti maneggevoli, costituite da icone (poste al di sopra della finestra di editing) che inseriscono il testo nel documento più velocemente di quanto un utente possa scrivere.

Questo documento descrivere come creare i file TagXML, il file description.rc e le barre degli strumenti. In breve, un &DTEP;.

I file TagXML (.tag) definiscono sia gli attributi specifici di un tag che la disposizione ed il contenuto della finestra di dialogo delle proprietà che &quantaplus; visualizza per il tag. Il file description.rc fornisce le regole e le informazioni del &DTEP; stesso. Le barre degli strumenti forniscono un mezzo veloce per aggiungere dei tag in un documento senza preoccuparsi di errori di ortografia e simili.

### Impacchettare

Le Cartelle dei Tag sono proprio questo, cartelle. Sono costituite solamente dai file description.rc e TagXML. Le Cartelle dei Tag portano il nome del linguaggio di markup e la sua versione, se applicabile. (Per esempio, html-4.01-strict)

### TagXML

La tabella sottostante elenca gli elementi definiti in TagXML e dichiara se sono fondamentali o meno. Anche se non tutti sono fondamentali, ti raccomandiamo di utilizzarne quanti più ne puoi così che gli altri utenti possano avere un'esperienza migliore e maggiori informazioni con cui lavorare.

Elemento | Utilizzo Predefinito | Tipologia di Utilizzo
--- | --- | ---
TAGS | fondamentale | sempre
tag | fondamentale | sempre
label | opzionale | fondamentale per creare una finestra di dialogo delle proprietà
attr | opzionale | fondamentale per definire un attributo
tooltip | opzionale | fondamentale per far si che la finestra di dialogo delle proprietà visualizzi un suggerimento
whatsthis | opzionale | fondamentale per far si che la finestra di dialogo delle proprietà visualizzi un Che cos è
list | opzionale | fondamentale quando un attributo è del tipo list
item | opzionale | fondamentale quando viene utilizzato <list >
textlocation | opzionale | sempre
location | opzionale | fondamentale quando viene utilizzata un'etichetta
text | opzionale | fondamentale quando viene utilizzata un'etichetta
children | opzionale | elenco dei tag che appaiono all'interno dei tag che si stanno definendo
child | fondamentale | un elemento figlio
stoppingtags | opzionale | elenco dei tag che dicono ad un altro tag di terminare
stoppingtag | fondamentale | una voce stoppingtags

#### Descrizione degli Elementi TagXML

La prossima sezione descriverà, nel dettaglio, ogni elemento. Tutto a partire da dove possono essere utilizzati a ciò che va inserito al loro interno verrà analizzato in una maniera semplice da seguire.

##### TAGS

Questo è l'elemento radice di ogni documento TagXML. Può apparire in un documento un sola volta. Può contenere la definizione di diversi tag. È un tipo di elemento solo-elemento.

Genitore(i) | Figli
--- | ---
NESSUNO | tag

##### tag

Contenitore per il tag che si sta definendo. Questo è un elemento di tipo solo-elemento.

Genitore(i) | Figli
--- | ---
TAGS | label, attr, stoppingtags

Attributo | Tipo | Valori | Predefinito | Uso | Descrizione
--- | --- | --- | --- | --- | ---
name | string |  |  | fondamentale | Specifica il nome del tag da definire.
single | boolean |  |  | opzionale | Specifica se il tag richiede o meno un tag di chiusura </(nometag) >.
type | string |  | xmltag | opzionale | Specifica il tipo di tag che si sta definendo.
|  | xmltag |  |  | Il tipo di tag è basato su XML. (Solamente Famiglia 1.)
|  | property |  |  | Il tipo di tag è relativo a &CSS;. (Solamente Famiglia 2.)
|  | function |  |  | Il tipo di tag è una funzione script. Quando viene usato <attr > rappresenta gli argomenti della funzione. (Solamente Famiglia 2.)
|  | class |  |  | Il tipo di tag è una classe script. (Solamente Famiglia 2.)
returnType | string |  | void | opzionale | Specifica il tipo di valore restituito dal tag che si sta definendo. (Solamente Famiglia 2.)
|  | void |  |  | Il tipo di tag restituisce void.
|  | int |  |  | Il tipo di tag restituisce int.
|  | float |  |  | Il tipo di tag restituisce float.
|  | long |  |  | Il tipo di tag restituisce long.
|  | string |  |  | Il tipo di tag restituisce string.

##### label

Posiziona un'etichetta nella finestra di dialogo. Il testo è specificato dal tag <text >. Questo è un elemento di tipo solo-elemento.

Genitore(i) | Figli
--- | ---
tag | text, location

##### attr

Definisce un attributo del tag. Questo elemento occorre una volta per ogni attributo. Definisce il nome ed il tipo di attributo. Inoltre contiene dei tag addizionali che specificano come dovrebbe essere visualizzato questo attributo e così via. Questo è un elemento di tipo solo-elemento.

Genitore(i) | Figli
--- | ---
tag | location, list, tooltip, whatsthis, textlocation

Attributo | Tipo | Valori | Predefinito | Uso | Descrizione
--- | --- | --- | --- | --- | ---
name | string |  |  | fondamentale | Specifica il nome dell'attributo che si sta definendo.
type | string |  | input | fondamentale | Specifica il tipo di attributo che si sta definendo.
|  | input |  |  | Il campo supporta testo libero (campo testo).
|  | check |  |  | Il valore del campo è boolean (casella di selezione).
|  | color |  |  | Il valore del campo è un colore.
|  | url |  |  | Il valore del campo è un &URL;. (File locale a cui fare riferimento.)
|  | list |  |  | Il valore del campo è un elemento di una lista specificata.
status | string |  | opzionale | fondamentale | Specifica se l'argomento è fondamentale o meno. (Solamente Famiglia 2.)
|  | opzionale |  |  | L'argomento è opzionale.
|  | fondamentale |  |  | L'argomento è fondamentale.
|  | implicato |  |  | L'argomento è implicato.

##### tooltip

Definisce il suggerimento per un campo nella finestra di dialogo. Questo elemento è di tipo solo-testo.

Per ora, è supportato solamente il testo semplice (non puoi usare nessun markup).

Genitore(i) | Figli
--- | ---
attr | NESSUNO

##### whatsthis

Definisce l'aiuto 'Che cos è di un campo nella finestra di dialogo. Questo elemento è di tipo solo-testo.

Per ora, è supportato solamente il testo semplice (non puoi usare nessun markup).

Genitore(i) | Figli
--- | ---
attr | NESSUNO

##### list

Un tag contenitore che raggruppa insieme gli elementi di una lista. Può apparire solamente una volta per ogni descrizione di attributo. Questo è un elemento di tipo solo-elemento.

Genitore(i) | Figli
--- | ---
attr | item

##### item

Definisce un elemento in una lista. Questo elemento è di tipo solo-testo.

Genitore(i) | Figli
--- | ---
list | NESSUNO

##### textlocation

Specifica la posizione del testo dell'attributo di un tag all'interno di una finestra di dialogo. Questo tag può apparire una sola volta per ogni attributo nella finestra di dialogo (cioè una volta per ogni tag <attr >). Questo elemento è di tipo vuoto.

Genitore(i) | Figli
--- | ---
attr | NESSUNO

Attributo | Tipo | Uso | Descrizione
--- | --- | --- | ---
row | nonNegativeInteger | fondamentale | Specifica la riga nella disposizione della finestra di dialogo di un campo o di una etichetta.
col | nonNegativeInteger | fondamentale | Specifica la colonna nella disposizione della finestra di dialogo di un campo o di una etichetta.
rowspan | nonNegativeInteger | opzionale | Specifica il numero di righe che un campo dovrebbe occupare.
colspan | nonNegativeInteger | opzionale | Specifica il numero di colonne che un campo dovrebbe occupare.

##### location

Specifica la posizione e la dimensione di un campo nella finestra di dialogo. Questo tag dovrebbe occorrere una sola volta per ogni campo nella finestra di dialogo (cioè una volta per ogni tag <attr > e <label >). Questo elemento è di tipo vuoto.

Genitore(i) | Figli
--- | ---
label, attr | NESSUNO

Attributo | Tipo | Uso | Descrizione
--- | --- | --- | ---
row | nonNegativeInteger | fondamentale | Specifica la riga nella disposizione della finestra di dialogo di un campo o di una etichetta.
col | nonNegativeInteger | fondamentale | Specifica la colonna nella disposizione della finestra di dialogo di un campo o di una etichetta.
rowspan | nonNegativeInteger | opzionale | Specifica il numero di righe che un campo dovrebbe occupare.
colspan | nonNegativeInteger | opzionale | Specifica il numero di colonne che un campo dovrebbe occupare.

##### text

Definisce il testo di un'etichetta o di una casella di selezione. Questo elemento è di tipo solo-testo.

Genitore(i) | Figli
--- | ---
label, attr | NESSUNO

##### children

Definisce una lista di elementi che possono apparire all'interno del tag che si sta definendo. Questo elemento è di tipo solo-elemento.

Genitore(i) | Figli
--- | ---
tag | child

##### child

Definisce un tag figlio. Questo elemento è di tipo vuoto.

Genitore(i) | Figli
--- | ---
children | NESSUNO

Attributo | Tipo | Uso | Descrizione
--- | --- | --- | ---
name | string | fondamentale | Specifica un tag che può apparire all'interno di un certo tag.

##### stoppingtags

Definisce una lista di elementi che forzano la chiusura di un tag. Questo elemento è di tipo solo-elemento.

Genitore(i) | Figli
--- | ---
tag | stoppingtag

##### stoppingtag

Definisce un tag di stop. Questo elemento è di tipo vuoto.

Genitore(i) | Figli
--- | ---
stoppingtags | NESSUNO

Attributo | Tipo | Uso | Descrizione
--- | --- | --- | ---
name | string | fondamentale | Specifica quali tag forzano la chiusura di altri tag.

#### Utilizzo di TagXML

Tutti i file TagXML devono iniziare con la dichiarazione &XML;: <?xml version="1.0" encoding="UTF-8"?> e devono essere annidati e conclusi correttamente.

Gli spazi bianchi non influenzano negativamente nulla, ma fai attenzione con i caratteri & e <. Questi dovrebbero solitamente essere sostituiti rispettivamente da &amp; e &lt;, in elementi come <tooltip >, <whatsthis >, e <text >. Non farlo non causerà un crash, ma pezzi del tuo lavoro spariranno.

#### Validazione dei file TagXML

Per validare i tuoi file TagXML, fai clic semplicemente sulla finestra di dialogo a comparsa Strumenti in cima a &quantaplus; e seleziona Valida TagXML. Verrà aperta una finestra di dialogo e dovrai solo seguire le sue semplice indicazioni.

Questa funzionalità non è al momento presente. Per ora la validazione avviene quando i file TagXML sono caricati in &quantaplus;.

#### Esempi di TagXML

##### Famiglia 1

Il paragrafo che segue ti mostrerà un file TagXML valido per la Famiglia 1. Questo file descrive l'elemento <schema > dell'&XML; &W3C;. Il nome di questo file TagXML dovrebbe essere schema.tag. Semplice, no?

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE TAGS>
    <TAGS>
     <tag name="schema">
      <label>
       <text
    >id</text>
       <location col="0" row="0"/>
      </label>
      <attr name="id" type="input">
       <tooltip
    >Un ID unico per l'elemento.</tooltip>
       <whatsthis
    >Un ID unico per l'elemento.</whatsthis>
       <location col="1" row="0"/>
      </attr>

      <label>
       <text
    >version</text>
       <location col="0" row="1"/>
      </label>
      <attr name="version" type="input">
       <tooltip
    >Versione dello schema.</tooltip>
       <whatsthis
    >Versione dello schema.</whatsthis>
       <location col="1" row="1"/>
      </attr>

      <label>
       <text
    >targetNamespace</text>
       <location col="0" row="2"/>
      </label>
      <attr name="targetNamespace" type="input">
       <tooltip
    >Riferimento &URI; dello spazio dei nomi di questo schema.</tooltip>
       <whatsthis
    >Riferimento &URI; dello spazio dei nomi di questo schema.</whatsthis>
       <location col="1" row="2"/>
      </attr>

      <label>
       <text
    >xmlns</text>
       <location col="0" row="3"/>
      </label>
      <attr name="xmlns" type="input">
       <tooltip
    >Riferimento &URI; per uno o più spazi dei nomeda utilizzare in questo schema.
       Se non viene utilizzato alcun prefisso, allora i componenti dello spazio dei nomi potrebbero essere usati senza qualifica.</tooltip>
       <whatsthis
    >Riferimento &URI; per uno o più spazi dei nome da utilizzare in questo schema.
       Se non viene utilizzato alcun prefisso, allora i componenti dello spazio dei nomi potrebbero essere usati senza qualifica.</whatsthis>
       <location col="1" row="3"/>
      </attr>

      <label>
       <text
    >attributeFormDefault</text>
       <location col="0" row="4"/>
      </label>
      <attr name="attributeFormDefault" type="list">
       <items>
        <item
    >qualified</item>
        <item
    >unqualified</item>
       </items>
       <tooltip
    >Forma predefinita per tutti gli attributi all'interno di questo schema.</tooltip>
       <whatsthis
    >Forma predefinita per tutti gli attributi all'interno di questo schema.</whatsthis>
       <location col="1" row="4"/>
      </attr>

      <label>
       <text
    >elementFormDefault</text>
       <location col="0" row="5"/>
      </label>
      <attr name="elementFormDefault" type="list">
       <items>
        <item
    >qualified</item>
        <item
    >unqualified</item>
       </items>
       <tooltip
    >Forma predefinita per tutti gli elementi all'interno di questo schema.</tooltip>
       <whatsthis
    >Forma predefinita per tutti gli elementi all'interno di questo schema.</whatsthis>
       <location col="1" row="5"/>
      </attr>

      <label>
       <text
    >blockDefault</text>
       <location col="0" row="6"/>
      </label>
      <attr name="blockDefault" type="input">
       <location col="1" row="6"/>
      </attr>

      <label>
       <text
    >finalDefault</text>
       <location col="0" row="7"/>
      </label>
      <attr name="finalDefault" type="input">
       <location col="1" row="7"/>
      </attr>
     </tag>
    </TAGS>

##### Famiglia 2

Quanto segue ti mostrerà un file TagXML valido della Famiglia 2. Questo file descrive la funzione overload di &PHP;. Il nome di questo file TagXML dovrebbe essere overload.tag.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE tags>
    <tags>
      <tag name="overload" type="function" returnType="void">
    <attr name="class_name" type="string" status="optional"/>
      </tag>
    </tags>

### description.rc

Il file description.rc, inoltre, è molto semplice. Non tutto quello che segue deve usato. La struttura base del file description.rc è la seguente.

#### Struttura Famiglia 1

    [General] - Informazioni generiche.
    Version = Usa 1 per &quantaplus; versione <=3.1.2 e 2 per qualsiasi versione successiva.
    Name = Stringa di definizione del DTD. (-//&W3C;//DTD HTML 4.01 Transitional//EN)
    NickName = il nome più gradevole del DTD. (HTML 4.01 Transitional). Se non definito, Name viene
    utilizzato come NickName.
    &URL; = &URL; che punta alla definizione del DTD. (http://www.w3.org/TR/html4/loose.dtd)
    DoctypeString = La stringa che dovrebbe apparire nella dichiarazione !DOCTYPE.
    (HTML PUBLIC "-//&W3C;//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd")
    Inherits = Il nome del DTD dal quale eredita i proprio tag questo DTD. (-//&W3C;//DTD HTML 4.01//EN)
    DefaultExtension = I nuovi file sono creati con questa estensione. (html)
    Groups = La lista dei gruppi di attributi comuni, che potrebbe essere presente in più di un tag.
    (Core, I18n, Script) Guarda sotto. (Gruppo1, Gruppo2...)
    NumOfPages = Il numero di pagine possedute dalla finestra di dialogo di un tag, a lato della pagina
    contenente gli attributi definiti nel file tag. Guarda sotto. (Pagina1,...)
    CaseSensitive = Comportamento con maiuscole/minuscole del DTD. (true|false)
    Family = 1 Questo tipo di DTEP è della Famiglia 1, dato è che di markup.

    [Toolbars] - Informazioni riguardo alle barre degli strumenti DTEP.
    Location = Il nome della cartella all'interno di
    $KDEDIR($KDEHOME)/share/apps/quanta/toolbars
    dove si trovano le barre degli strumenti per questo DTEP.
    Names = La lista dei nomi dei file delle barre degli strumenti, senza l'estensione .toolbar.tgz,
    che sono caricate per questo DTEP dalla cartella indicata sopra.

    [Gruppo1] - Sostituisci con uno dei Gruppi elencati in seguito.
    Attributes = La lista degli attributi per questo gruppo. Al momento, tutti gli attributi elencati sono
     considerati come stringhe.
    Ad esempio:
    [Core]
    Attributes = id, class, style, title

    [Pagina1] - Descrizione della pagina di modifica di un tag.
    Title = Il titolo di questa pagina nella finestra di dialogo di modifica del tag.
    Groups = Lista dei gruppi che appaiono su questa pagina. (Core, I18n)

    [Extra rules] - Alcune regole non appartenenti ad altre sezioni.
    BooleanAttributes = (simple|complex)
    Esempio per semplice: <tag booleanAttr
    >.
    Esempio per complesso: <tag booleanAttr="1"
    > o <tag booleanAttr="true">
    Single Tag Style = (html|XML)
    Esempio per html: <single_tag>
    Esempio per XML: <single_tag />
    StructGroupsCount = Il numero di gruppi di strutture. Guarda sotto.
    MinusAllowedInWords = Se vero "questa-è-una-parola" viene trattata come una parola,
    altrimenti viene considerata come 4 parole.
    TagAutoCompleteAfter = CHAR. La finestra di auto-completamento viene aperta automaticamente
    una volta che questo CHAR viene digitato o viene premuto SPAZIO dopo questo CHAR. Per
    DTEP della Famiglia 1 di solito è "<" Il testo "none" al posto di un CHAR specifica
    che la finestra di completamento del tag non dovrebbe essere aperta in maniera automatica
    ma solo quando l'utente lo richiede.
    AttributeSeparator = CHAR. Questo CHAR significa che il nome dell'attributo è terminato.
    Server per i "DTEP XML".
    TagSeparator = CHAR. Simile al precedente.

    [StructGruppo_1] - Definizione della struttura del gruppo 1.
    Name = Il testo che appare se ci sono dei tag che corrispondono alle impostazioni
    di questo gruppo.
    No_Name = Il testo che appare se nessun tag corrisponde alle impostazioni
    di questo gruppo.
    Icon = Il nome dell'icona che appare prima del testo specificato prima.
    Tag = nometag(attributo1, attributo2, ...). I tag col nome nometag appariranno
    sotto questo gruppo. Il testo dell'elemento sarà "attributo1_value | attributo2_value | ..."
    Al momento solamente un tag può essere elencato qui.
    HasFileName = (true|false) True, se il testo dell'elemento (i valori dell'attributo sopra)
    contengono il nome di un file.
    FileNameRx = Espressione regolare utilizzata per rimuovere i caratteri non necessari dal
    testo dell'elemento.

    [Parsing rules] - Regole utilizzate quando si esegue l'analisi del documento.
    SpecialAreas = Le stringhe di inizio e di fine delle aree speciali, separate da una virgola.
    Le aree speciali non sono analizzate secondo le regole di questo DTEP, ma secondo le proprie regole.
    Un'area speciale può essere un DTEP di un'altra famiglia, un commento o qualcos altro.
    Ad esempio <!-- -->
    SpecialAreaNames = Lista di elementi separati da virgole delle aree speciali indicate sopra.
    Ad esempio comment
    SpecialTags = nometag(nomeattributo) - Specifica un tag che definisce l'inizio di un'area speciale.
    MayContain = Lista di elementi separati da virgole di DTEP della famiglia 2 che possono essere
    presenti nel documento. (php, css)

#### Struttura Famiglia 2

    [General] - Informazioni generiche.
    Version = Usa 1 per &quantaplus; versione <=3.1.2 e 2 per qualsiasi versione successiva.
    Name = Nome proprio
    NickName = Il nome con cui viene comunemente chiamato. Se non è definito, Name viene usato come NickName.
    Inherits = Il nome del DTEP dal quale questo DTEP eredita i tag. (Il Nome, non il Soprannome)
    DefaultExtension = I nuovi file sono creati con questa estensione. (php)
    NumOfPages = 0   Sempre zero perché non c'è una finestra di dialogo di modifica del tag per
    DTEP della Famiglia 2.
    CaseSensitive = Comportamento con maiuscole/minuscole del DTD. (true|false)
    Family = 2 Questo tipo di DTEP è della famiglia 2, dato che non è di markup.

    [Toolbars] - Informazioni riguardo alle barre degli strumenti del DTEP
    Location = Il nome della cartella all'interno di $KDEDIR($KDEHOME)/share/apps/quanta/toolbars
    dove si trovano le barre degli strumenti di questo DTEP.
    Names = La lista dei nome dei file delle barre degli strumenti, senza l'estensione .toolbar.tgz, che
    sono caricate per questo DTEP dalla cartella indicata prima.

    [Extra rules] - Alcune regole non appartenenti ad altre sezioni.
    BooleanAttributes = (simple|complex)
    Esempio per semplice: <tag booleanAttr
    >.
    Esempio per complesso: <tag booleanAttr="1"
    > o <tag booleanAttr="true">
    StructGroupsCount = Il numero di gruppi di strutture. Guarda sotto.
    MinusAllowedInWords = Se vero "questa-è-una-parola" viene trattata come una parola,
    altrimenti viene considerata come 4 parole.
    TagAutoCompleteAfter = CHAR. La finestra di auto-completamento viene aperta automaticamente
    una volte che viene digitato questo CHAR o che viene premuto SPAZIO dopo questo CHAR. Per
    DTEP della Famiglia 1,
    è solitamente "<". Il testo "none" al posto di un CHAR specifica che la finestra di
    auto-completamento non dovrebbe essere aperta automaticamente, ma solamente se l'utente lo richiede.
    AttributeSeparator = CHAR. Questo CHAR significa che il nome dell'attributo è terminato.
    Per i DTEP XML è ".
    TagSeparator = CHAR. Simile a sopra.
    AttributeAutoCompletionAfter = CHAR. Simile a TagAutoCompletionAfter, ma
    per gli attributi dei tag. È "(" per default e ":" per CSS).

    [StructGruppo_1] - Definizione della struttura del gruppo 1.
    Name = Il testo che appare se ci sono tag che corrispondono alle impostazioni di questo gruppo.
    No_Name = Il testo che appare se non ci sono tag che corrispondono alle impostazioni di questo gruppo
    Icon = Il nome dell'icona che appare prima del testo indicato sopra.
    Tag = nometag(attributo1, attributo2, ...). I tag chiamati nometag appariranno
    sotto a questo gruppo. Il testo dell'elemento sarà "attributo1_value | attributo2_value | ..."
    Al momento solo un tag può essere elencato qui.
    HasFileName = (true|false) True, se il testo dell'elemento (i valori dell'attributo indicati prima)
    contiene il nome di un file.
    FileNameRx = espressione regolare usata per scartare i caratteri non necessari dall'elemento testo.
    SearchRx = espressione regolare usata per trovare le aree di testo nel DTEP della Famiglia 2,
    che apparterranno a questo gruppo.
    ClearRx = espressione regolare usata per cancellare testo/caratteri non desiderati dal risultato
    della ricerca indicata prima. La stringa ripulita apparirà nella struttura ad albero.

    [Parsing rules] - Regole usate quando si analizza un documento.
    SpecialAreas = La stringhe di inizio e fine delle aree speciali, separate da una virgola.
    Le aree speciali non vengono analizzate secondo le regole di questo DTEP ma secondo le proprie regole.
    Un'area speciale può essere un DTEP di un'altra famiglia, un commento o qualcosa di analogo.
    Ad esempio <!-- -->
    SpecialAreaNames = Lista delle aree speciali indicate prima, separate da una virgola
    Ad esempio comment
    SpecialTags = nometag(nomeattributo) - Specifica un tag che definisce l'inizio di un'area speciale.
    AreaBorders = Lista degli elementi bordo che racchiudono l'area di questo DTEP della Famiglia 2. Nel caso
    di PHP, è: <? ?>, <* *
    >, <% %>
    Tags = nometag(attributo). Se il DTD padre (reale) ha un tag nometag e il valore dell'attributo
    di questo tag è identico al nome del DTD, l'area indicata dal tag viene analizzata secondo le regole di questo DTD.
    Comments = lista di indicatori di area dei commenti, separati da virgole. EOL significa fine della riga.
    Ad esempio: // EOL, /* */
    StructKeywords = Lista di parole chiave di struttura separate da punti e virgola. Le strutture sono
    considerate come nuovi nodi nell'albero della struttura.
    StructBeginStr = Una stringa che specifica l'inizio di una struttura (come {)
    StructEndStr = Una stringa che specifica la fine di una struttura (come })
    StructRx = Espressione regolare contente l'inizio o la fine dell'area della struttura.
    Ad esempio: \\{ | \\} (i bordi dell'area della struttura possono essere { o })

## Creare Barre degli strumenti

Quanto segue ti mostrerà come creare barre degli strumenti per un &DTEP;. Le barre degli strumenti sono degli elementi grafici cui sono assegnate delle azioni. Le azioni in &quantaplus;, sono alla base di quasi tutte le estensioni che &quantaplus; possiede e che acquisirà in futuro. Lo stesso meccanismo che definisce un azione in &quantaplus; abilita anche l'auto-completamento nelle finestre di dialogo dei tag. L'utilizzo che puoi fare delle azioni è virtualmente illimitato. Per fare un esempio, useremo &HTML; tidy sulle nostre pagine web.

### Da Zero al Completo

Per iniziare, dovrai creare una barra degli strumenti dell'utente. Seleziona Barre degli strumenti Aggiungi Barra degli strumenti dell'Utente .

Se ci sono molti tag per il linguaggio di markup, ti raccomandiamo di dividerli in gruppi logici. Avrai bisogno di creare una nuova barra degli strumenti per ogni gruppo. In questo caso, non ce ne sono molti, perciò costruiremo solamente una barra degli strumenti e la chiameremo con il nome del markup.

Una volta che saranno create tutte le tue barre degli strumenti, dovrai aggiungere e configurare le azioni. Per questo, seleziona Impostazioni Configura Azioni .

Le parti di questa finestra sono molto chiare. Premi il pulsante Nuova azione alla base della finestra per entrare nella modalità di modifica.

Completa tutti i campi necessari ed aggiungi il tag alla(/e) barra(/e) degli strumenti appropriata(/e).

Completa il resto e, se il tag ha degli attributi ed hai intenzioni di usarli sempre, attiva la casella Apri finestra di dialogo "Modifica tag" se disponibile così che ti venga proposta ogni volta che usi questa azioni.

Dovresti aver ottenuto ora qualcosa di molto simile a quanto segue.

Premi il pulsante Applica per vedere l'azione aggiunta alla(/e) barra(/e) degli strumenti che hai selezionato.

Oh no! Quell'icona è orribile. Come farete tu e gli altri a ricordare che quell'icona è associata a quell'azione? Sostituiamola prima che sopraggiungano dei problemi.

Per creare un'icona che descriva in maniera più accurata quell'azione, utilizzeremo &kiconedit;. Selezionalo dal &kmenu;, Grafica More Applications (o dove l'ha posto la tua distribuzione).

&kiconedit; inizia per impostazione predefinita con la dimensione di 32x32 pixel, ma noi abbiamo bisogno di 22x22. Per cambiare, seleziona Modifica Ridimensiona .

Tieni a mente che stai creando un'icona che non aiuterà solo te a ricordare quale azione fa cosa, ma anche agli altri utenti del &DTEP;.

Dato che il tag per cui sto creando l'icona è chiamato inizio, ho deciso di creare un segnale di Start. Usando il colore verde (il verde viene spesso interpretato come vai, inizio o procedi) porterà, o dovrebbe trasmettere un messaggio all'utente che facendo clic su questa azione verrà posto un tag <start> nel documento corrente.

Adesso che ho finito con la creazione dell'icona, la salverò.

Una volta che avrai finito di creare l'icona, dovrai associarla con l'azione. Per farlo, apri di nuovo (in &quantaplus;) Impostazioni Configura Azioni e seleziona l'azione per cui hai creato l'icona. A lato del campo Testo, vedrai un pulsante su cui fare clic.

Seleziona Altre Icone e poi fai clic sul pulsante Sfoglia.

Raggiungi la cartella in cui hai salvato l'icona, selezionala e fai clic su OK.

Premi il pulsante Applica e fai lo stesso per tutti gli altri tag, se ce ne sono, o fai clic su OK per finire.

Supponiamo che tu voglia aggiungere alcune tipiche funzioni di &quantaplus; alla tua barra degli strumenti o magari pensi che la barra degli strumenti sarebbe meglio organizzata in una differente maniera con alcuni separatori per raggruppare le azioni. Apri la finestra di dialogo Configura le barre degli strumenti andando su Impostazioni Configura le barre degli strumenti . Assicurati che la tua barra degli strumenti sia selezionata.

Sceglierò il separatore (in cima alla colonna di sinistra) per la mia barra degli strumenti. Una volta selezionato l'elemento che vuoi aggiungere alla tua barra degli strumenti, premi il pulsante con la freccia a destra. Così verrà aggiunto alla tua barra degli strumenti.

Penso che avrò bisogno di una maniera rapida per accedere all'Anteprima di Konqueror. La selezionerò e l'aggiungerò alla barra degli strumenti.

Nota come il separatore aiuti a raggruppare. Un utente privo di esperienza avrebbe potuto pensare che il pulsante di &konqueror; fosse stato analogo o addirittura opposto al pulsante start.

Applica le tue modifiche e, quando hai terminato, premi OK per finire.

Ah, guarda alla nuova e fantastica barra degli strumenti! Molto più maneggevole ora.

Ricordati di verificare la tua barra degli strumenti, facendo clic su tutti i pulsanti, così da verificare che l'output sia corretto.

Ora, per salvare la barra degli strumenti, selezioneremo Barre degli strumenti Salva barre degli strumenti Salva con nome la barra degli strumenti locale .

Salvala nella cartella corretta. Dato che NeXML non esiste, la metterò nella cartella di primo livello, ma la tua barra degli strumenti dovrebbe essere salvata nella cartella corretta. Assicurati di impostare il tuo file description.rc così da caricare la tua barra degli strumenti quando viene creato un nuovo file di quel tipo.

## Creare la Tua Documentazione

Robert
Nickel

    robert@artnickel.com

Samuele
Kaplun

    kaplun@aliceposta.it

Traduzione del documento

## Creare la Tua Documentazione

Le aggiunte più evidenti in &quantaplus; per l'utente generico saranno, probabilmente, l'aggiunta della documentazione per il linguaggio markup o scripting che ti piace di più. Per questo, questo capitolo spiegherà come creare l'albero della documentazione di &PHP; per il mio uso personale.

Prima di iniziare a creare la tua documentazione, potresti voler controllare l'archivio di &quantaplus; per vedere se qualcun altro l'ha già creata.

Ci sono due fasi in questo processo. Primo, devi procurarti la documentazione esistente per il linguaggio di markup/scripting/eccetera che stai curando. Secondo, devi creare il file `docrc`. La prima fase dipende da te, la seconda è quella che affronteremo ora.

La forma generica del file docrc è la seguente:

    #File di Configurazione di KDE
    [Tree]
    Doc dir=percorso, relativamente a questo file, per i file html della documentazione ad esempio, php42/
    #elementi di primo livello
    Top Element=La tua descrizione per questa documentazione Ad esempio, documentazione &PHP; 4.2

    Sezione 1=Sezione1.html
    Sezione 2=#Sez2.1,#Sez2.2,#Sez2.3
    Sez2.1=Sez2.1.html
    Sez2.2=Sez2.2.html
    Sez2.3=Sez2.3.html
    ...

    [Context]
    ContextList=funz1,funz2,tag1,tag2,tag3
    funz1=funz1.html
    funz2=funz2.html
    tag1=tag1.html
    tag2=tag2.html
    tag3=tag3.html

Il file `docrc` è suddiviso in due sezioni: Albero e Contesto.

La sezione Tree definisce l'aspetto con cui viene presentata la documentazione nella scheda omonima. Per esempio, potrai osservare che con la documentazione di &PHP; hai qualcosa di simile a:

Facendo riferimento a quanto mostrato sopra, il mio file `docrc` di &PHP; appare così:

    #KDE Config File

    [Tree]

    Doc dir=php42/

    #top level elements
    Top Element=PHP 4.2 documentation

    PHP 4.2 documentation=Table of Contents,#Getting Started,#Language Reference

    Table of Contents=index.html

    Getting Started=Introduction, ...
    Introduction=introduction.html
    ...

    Language Reference=Basic syntax, ...
    Basic syntax=language.basic-syntax.html
    ...

Osserva il `#` davanti a Getting Started e Language Reference. Questo sta ad indicare che questi sono sotto-contenitori dell'albero e che hanno un proprio contenuto. Non credo che ci sia un limite al livello di profondità (oltre a quello indicato dal buonsenso) — usa il tuo giudizio.

Per il Sommario, avrai notato che fa riferimento direttamente ad un file (e di conseguenza appare in fondo alla rappresentazione dell'albero — le cartelle vengono prima!).

Gli spazi non influiscono su nulla, ma fai attenzione ai caratteri & e <. Questi dovrebbero essere sostituiti rispettivamente da &amp; e &lt; in tutti i file di risorsa di &quantaplus; basati su &XML;.

La sezione Context è la sezione del file docrc che viene usata per facilitare l'aiuto sensibile al contesto. Per esempio, stai scrivendo uno script &PHP; e desideri vedere la documentazione per la funzione `mysql_fetch_array`. Evidenzia semplicemente la funzione e premi &Ctrl;H per l'aiuto contestuale. Verrà immediatamente visualizzata la documentazione di `mysql_fetch_array`. Ci sono solo due tipi di voci qui: ContextList e le righe di associazione ai file.

ContextList

  Molto semplicemente, questa è solo una lista di voci di contesto, separati da una virgola, che desideri siano disponibili (per &PHP;, questi sono le funzioni di &PHP;).

Righe di associazioni dei file

  Queste sono nella forma elemento di contesto=pagina della documentazione html. Ad esempio acos=function.acos.html

Una versione ridotta della sezione Contesto del mio `docrc` è la seguente:

    #Parole chiave per l'aiuto contestuale
    [Context]
    ContextList=abs,acos,acosh,addcslashes,addslashes,...

    abs=function.abs.html
    acos=function.acos.html
    acosh=function.acosh.html
    addcslashes=function.addcslashes.html
    addslashes=function.addslashes.html
    ...

Adesso basta che salvi il tuo file `docrc`, in `$`HOME`/.kde/share/apps/quanta/doc` o `$`KDEDIR`/share/apps/quanta/doc` rispettivamente per un uso locale o globale. Poi devi creare una cartella (quella specificata nel tuo file `docrc`) nella stessa cartella del tuo file `docrc` e copiare lì le tue pagine &HTML;.

Dovrai riavviare &quantaplus; per vedere la tua documentazione.

Una volta che ti sei accertato che siano buoni e valga la pena condividerli, spedisci il file `docrc` assieme ad una descrizione riguardo a qualsiasi informazione pertinente su quale documentazione tu abbia usato all'archivio di &quantaplus; perché venga usato dalla comunità di &quantaplus;. Non diventerai ricco, ma ti sentirai gratificato sapendo di aver contribuito qualcosa alla miglior piattaforma di sviluppo web che esista.