Estendere &quantaplus; Christopher Hornbaker
chrishornbaker@earthlink.net
András Mantia
amantia@kde.org
SamueleKaplun
samuele.kaplun@collegiodimilano.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. I &DTEP; sono di due tipi, Famiglia 1, per il markup e Famiglia 2 per lo scripting ed il &CSS;. I &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 &descriptionrc; 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. I &DTEP; possono essere creati manualmente (guarda più avanti), scaricati o creati automaticamente da DTD esistenti. Guarda per i dettagli sulla conversione. Questo documento descrive come creare i file TagXML, il file &descriptionrc; 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 &descriptionrc; 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 &descriptionrc; 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 sì che la finestra di dialogo delle proprietà visualizzi un suggerimento whatsthis opzionale fondamentale per far sì 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 una 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 AttributoTypeValori PredefinitoUsoDescrizione namestring fondamentaleSpecifica il nome del tag da definire. singleboolean opzionaleSpecifica se il tag richiede o meno un tag di chiusura </(nometag)>. typestringxmltag opzionaleSpecifica il tipo di tag che si sta definendo. xmltag Il tipo di tag è basato su XML. (Solamente Famiglia 1.) entity Il tag descrive un'entità. (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.) method Il tipo di tag è un metodo di classe. (Solamente Famiglia 2.) returnTypestringvoid opzionaleSpecifica 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. versionstring opzionaleSpecifica la versione del linguaggio per cui è valido il tag extendsstring opzionaleValido solo nel caso in cui il tipo di tag è "class". Il nome della classe base per questa classe. (Solo Famiglia 2.) classstring opzionaleValido solo nel caso in cui il tipo è "method". Specifica il nome della classe a cui appartiene questo metodo. (Solo Famiglia 2.) commonboolean opzionaleSe "yes", il tag specifica un attributo comune per il gruppo e gli attributi all'interno di questo tag possono essere collegati a qualsiasi altro tag. (Solo Famiglia 1.) commentstring opzionalela stringa di commento appare vicino al nome del tag nella casella di completamento 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 AttributoTypeValori PredefinitoUsoDescrizione namestring fondamentaleSpecifica il nome dell'attributo che si sta definendo. typestringinput fondamentaleSpecifica 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. statusstringopzionale fondamentaleSpecifica se l'argomento è fondamentale o meno. (Solamente Famiglia 2.) opzionale L'argomento è opzionale. fondamentale L'argomento è fondamentale. implicato L'argomento è implicato. sourcestring opzionaleSpecifica il sorgente utilizzato per riempiere le voci dell'attributo nella finestra di dialogo dell'editor del tag e nell'albero degli attributi selection Il testo selezionato viene utilizzato come sorgente dcop Viene utilizzato come sorgente il risultato di un metodo dcop interfacestring opzionaleRichiede source="dcop". Viene utilizzata l'interfaccia dcop all'interno di &quantaplus; per ottenere la sorgente di dati. methodstring opzionaleRichiede source="dcop" ed il nome di un'interfaccia. Viene utilizzato come sorgente di dati il nome del metodo dcop all'interno di &quantaplus;. argumentsstring opzionaleRichiede source="dcop", il nome di un'interfaccia ed il nome di un metodo. Gli argomenti passati al metodo. Possono essere vuoti o "%tagname%", per il nome del tag corrente. 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 AttributoType UsoDescrizione rownonNegativeInteger fondamentaleSpecifica la riga nella disposizione della finestra di dialogo di un campo o di una etichetta. colnonNegativeInteger fondamentaleSpecifica la colonna nella disposizione della finestra di dialogo di un campo o di una etichetta. rowspannonNegativeInteger opzionaleSpecifica il numero di righe che un campo dovrebbe occupare. colspannonNegativeInteger opzionaleSpecifica 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, attrNESSUNO AttributoType UsoDescrizione rownonNegativeInteger fondamentaleSpecifica la riga nella disposizione della finestra di dialogo di un campo o di una etichetta. colnonNegativeInteger fondamentaleSpecifica la colonna nella disposizione della finestra di dialogo di un campo o di una etichetta. rowspannonNegativeInteger opzionaleSpecifica il numero di righe che un campo dovrebbe occupare. colspannonNegativeInteger opzionaleSpecifica 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, attrNESSUNO 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 tagchild child Definisce un tag figlio. Questo elemento è di tipo vuoto. Genitore(i)Figli childrenNESSUNO AttributoTypeValori UsoDescrizione namestring fondamentaleSpecifica un tag che può apparire all'interno di un certo tag. usagestring opzionaleSpecifica la relazione con il genitore. fondamentale Il genitore deve avere almeno un figlio con questo nome. stoppingtags Definisce una lista di elementi che forzano la chiusura di un tag. Questo elemento è di tipo solo-elemento. Genitore(i)Figli tagstoppingtag stoppingtag Definisce un tag di stop. Questo elemento è di tipo vuoto. Genitore(i)Figli stoppingtagsNESSUNO AttributoType UsoDescrizione namestring fondamentaleSpecifica 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 nome da 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> &descriptionrc; Il file &descriptionrc; è, inoltre, abbastanza semplice ed esiste un suo editor raggiungibile tramite DTDModifica impostazioni DTD. Verrà così modificato il file &descriptionrc; di un &DTEP; che puoi scegliere da una lista.Per modificare il file &descriptionrc; di un &DTEP; appena creato dovresti creare un semplice &descriptionrc; con le seguenti voci: [General] Version = Usa 1 per &quantaplus; version <=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 abbellito del DTD. (HTML 4.01 Transitional). Se non definito verrà utilizzato Name come NickName. Una volta creato mettilo assieme ai file tag, carica il &DTEP; appena creato con DTDCarica pacchetto DTD (DTEP). Quando sarà caricato potrai cominciare a modificare le impostazioni del &DTEP;. Controlla i suggerimenti e i testi del "Che cos'è?" per le varie voci della finestra di dialogo dell'editor per capire il significato di ogni voce. In alternativa puoi leggere quanta/data/dtep/dtd-description.txt dal pacchetto tar del sorgente che contiene una descrizione del formato. Azioni definite dall'utente Le azioni sono molto comuni in ogni applicazione. Facendo clic sull'icona di una barra degli strumenti, selezionando un elemento del menu o utilizzando una scorciatoia attiva di solito un'azione. In &quantaplus; le azioni vengono portate ad un livello superiore. Invece di essere cablate (cioè create dal programmatore applicativo a livello del codice sorgente) sono creabili e modificabili dall'utente ordinario, permettendo così di aggiungere nuove funzionalità a &quantaplus;. Queste sono le azioni definite dall'utente e persino molte delle azioni predefinite di &quantaplus; sono definite dall'utente (e modificabili dall'utente). Esistono tre tipi di azioni definibili dall'utente: Azioni testo Azioni tag Azioni script Creare le azioni Puoi creare un'azione tramite ImpostazioniConfigura azioni. Fai clic su Nuova azione per incontrare una finestra di dialogo simile alla seguente: Tipo Specifica il tipo di azione (Testo, Tag, Script). Testo Il nome dell'azione visibile all'utente. Il pulsante accanto all'etichetta Testo L'icona assegnata a quest'azione. Fai clic per modificare l'icona corrente. Suggerimenti Breve descrizione di cosa fa l'azione. Scorciatoia La scorciatoia assegnata a questa azione. Fai clic su Personalizzato o vicino al pulsante Personalizzato per assegnare una scorciatoia; fai clic suNessuno per rimuovere la scorciatoia attualmente assegnata. Contenitori della barra degli strumenti Le barre degli strumenti definite dall'utente dove questa azione appare. Vedi . Impostazioni dettagliate Specifica le impostazioni per differenti tipi di azioni. Vedi sotto. Azioni testo L'azione più semplice. Puoi inserire del testo nell'area Impostazioni dettagliate e ogni volta che l'azione verrà eseguita questo testo sarà inserito nel tuo documento alla posizione corrente del cursore. Vedi l'esempio sotto. Azioni tag Utile per inserire tag XML, ma puoi chiaramente utilizzarle per altri scopi. <tag> Il nome del tag. </tag> Se attivato quando l'azione viene eseguita questo testo sarà inserito come tag di chiusura. Se esiste un'area selezionata nel documento prima che tu esegua l'azione, il <tag> sarà inserito prima dell'area selezionata e </tag> dopo. Esegui "Modifica tag" se disponibile Se attivato ed esiste un file tagXML per questo tag, verrà mostrata una finestra di dialogo di modifica del tag prima dell'inserimento del tag stesso nel documento, così che tu possa regolare finemente gli attributi del tag. <tag> e </tag> saranno inseriti come sono stati digitati qui. I simboli <, > o / non verranno aggiunti automaticamente. Azioni script Il tipo di azione più potente. Con l'aiuto di questa azione puoi eseguire applicazioni esterne (di solito script, ma non vi è un limite particolare), che possono alterare il tuo documento o utilizzare il tuo documento (o parte del tuo documento) come input. Esempi di &quantaplus; stesso sono la finestra di dialogo Avvio rapido, le varie azioni Visualizza in... per i DTEP (X)HTML. Innanzitutto devi inserire il nome del tuo script incluso l'interprete. Ad esempio: sh /home/miaHome/mioScript.sh. Anche se puoi utilizzare percorsi completi, è preferibile usare la variabile %scriptdir nella riga di comando, come in sh %scriptdir/mioScript.sh. In questo modo &quantaplus; proverà a trovare il tuo script nelle seguenti posizioni: la cartella globale degli script: $TDEDIR/share/apps/quanta/scripts la cartella locale degli script: $TDEHOME/share/apps/quanta/scripts il tuo path: $PATH Esistono altre variabili speciali che puoi utilizzare sulla riga di comando: %f: verrà sostituita dall'URL del documento corrente. Nel caso di documenti locali, il prefisso file:/ verrà rimosso dal nome del documento. %input: verrà sostituita dall'input selezionato. Vedi sotto. %projectbase: verrà sostituita dall'URL del progetto corrente. È vuota se non è stato caricato alcun progetto. %pid: verrà sostituita dal PID del processo di &quantaplus; in esecuzione. Se &quantaplus; è in esecuzione in modalità unica, la stringa "unique" precederà il numero del PID. Utile quando vuoi usare DCOP per controllare &quantaplus; da uno script esterno. %userarguments: utile nel caso di eventi. Questa variabile verrà sostituita dalle proprietà degli eventi nel seguente ordine: Primo argomento L'id univoco dello script Secondo argomento il nome dell'evento Terzo argomento i parametri dell'evento, solitamente il nome del file del documento corrente o il percorso del file del progetto. Accanto ai precedenti metodi lo script può ricevere dell'input da &quantaplus; tramite lo standard input. Nella casella combo Input puoi selezionare che cosa deve essere inviato sullo standard input. Le scelte possibili sono: Nulla: non viene inviato nulla allo script. Documento corrente: viene inviato allo script l'intero documento. Testo selezionato: viene inviata allo script l'area del documento selezionata. L'utilizzo della variabile %input di solito ha senso solo quando si usa questa impostazione. In maniera simile alla voce Input puoi catturare l'output dell'applicazione eseguita. Ci sono due tipi di output: l'output normale, stampato sullo standard output; i messaggi di errore, stampati sullo standard error. Puoi specificare che cosa debba accadere al testo stampato sullo standard output, modificando il valore della casella combo Output: Nulla: l'output dell'applicazione viene ignorato. Inserisci nella posizione del cursore: l'output verrà inserito nel documento e nella posizione corrente. Sostituisci selezione: l'area selezionata del documento verrà sostituita dall'output. Sostituisci selezione: l'area selezionata del documento verrà sostituita dall'output. Crea un nuovo documento: verrà creato un nuovo documento contenente l'intero output dello script. Sostituisci il documento corrente: l'intero documento verrà sostituito dall'output. Finestra di messaggio: l'output apparirà nella vista Messaggi. Le scelte disponibili per lo standard error (Error) sono le stesse dell'output normale. 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 &tdeiconedit;. Selezionalo dal &kmenu;, Grafica More Applications (o dove l'ha posto la tua distribuzione). &tdeiconedit; 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 &descriptionrc; 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
SamueleKaplun
samuele.kaplun@collegiodimilano.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 è sufficiente salvare il tuo file docrc, in $HOME/.trinity/share/apps/quanta/doc o $TDEDIR/share/apps/quanta/doc rispettivamente per un uso locale o globale. Poi occorre 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.
Condivisione delle risorse Con &quantaplus; non sei solo. È possibile condividere con gli altri le diverse risorse (pacchetti DTEP, barre degli strumenti con le relative azioni, script, modelli). Ci sono due modi per farlo: Spedire via posta elettronica Le risorse possono essere inviate tramite posta elettronica ai tuoi amici, colleghi o altri. Troverai la voce di menu Invia per posta elettronica in diversi posti, ad esempio DTDInvia il pacchetto DTD (DTEP) per posta elettronica, Barre degli strumentiInvia barra degli strumenti per posta elettronica, nel menu contestuale dei file e delle cartelle negli alberi Modelli e Script. Spedire al server principale Le risorse possono essere spedite al nostro deposito principale, dal quale tutti gli altri utenti di &quantaplus; potranno scaricarle. Gli invii verranno esaminati e resi disponibili solo se la nostra squadra li considererà corretti ed utili per la pubblicazione. Per fare un invio valido ti suggeriamo di firmare le risorse, perciò hai bisogno di una chiave GPG/PGP. Questa informazione viene usata per verificare l'origine delle risorse sia dalla nostra squadra che dagli altri utenti. Riguardo a come ottenere delle risorse dal server principale . Durante l'invio ti verrà chiesto di inserire la parola chiave per la tua chiave segreta GPG (la parola chiave non verrà memorizzata), o nel caso tu abbia più chiavi segrete, ti verrà chiesto di scegliere quale intendi utilizzare. Nella finestra di dialogo Condividi le novità riempi gli appositi campi (la voce Anteprima URL potrà rimanere vuota) e inizia l'invio facendo clic su OK. Si può iniziare l'invio tramite il menu DTDInvia pacchetto DTD (DTEP), Barre degli strumentiInvia barra degli strumenti, nel menu contestuale dei file e delle cartelle nell'albero dei Modelli e degli Script. Ottenere le risorse È possibile aggiornare la tua installazione di &quantaplus; senza installarne una nuova versione, scaricando le nuove risorse come i pacchetti DTEP, le barre degli strumenti con le azioni, i modelli, gli script e la documentazione. Una delle possibilità è quella di ottenere le risorse tramite posta elettronica o di scaricarle da un server web, nel qual caso dovrai installarle manualmente. Se sarai fortunato troverai anche uno script di installazione allegato alla risorsa. &quantaplus; possiede, inoltre, un server dedicato per archiviare le risorse che non sono state incluse nella distribuzione principale o a causa delle loro dimensioni o del loro utilizzo poco frequente, o che sono state contribuite in seguito dagli utenti. Queste risorse vengono installate automaticamente. Per scaricarle utilizza le varie voci Scarica nei rispettivi menu. Puoi trovarli nel menu DTDScarica pacchetto DTD (DTEP), Barre degli strumentiScarica barra degli strumenti, nel menu contestuale di un'area libera nell'elemento radice degli alberi Modelli, Script e Documentazione. Dopo aver scaricato una risorsa, ma prima di averla installata, &quantaplus; ne verifica la validità, controllandone l'integrità e la firma elettronica. In caso di problemi li segnalerà e potrai decidere di continuare o meno. Per favore, leggi attentamente le finestre di dialogo. Nel caso in cui l'integrità sia corretta e la risorsa sia correttamente firmata, ti verrà comunque mostrata una finestra di dialogo informativa, così che tu possa vedere chi ha creato la risorsa. Assicurati di installare le risorse, specialmente per quanto riguarda le barre degli strumenti e gli script, solo da sorgenti sicuri! Convertire una DTD in una &DTEP; È possibile lavorare su linguaggi XML non supportati attualmente da &quantaplus; creandone il pacchetto DTEP. Ma la creazione potrebbe impiegare parecchio tempo, in quanto potresti dover creare centinaia di file tag nel formato tagXML. Chiaramente c'è un modo più rapido per farlo, convertendo automaticamente un DTD in un pacchetto DTEP. La conversione può essere avviata dal menu DTDCarica e converti DTD. Seleziona il file .dtd che definisce il DTD che desideri utilizzare. Vedrai così la finestra di dialogo: Le voci sono: Cartella di destinazione: il nuovo &DTEP; appena creato verrà posto in una cartella con questo nome al di sotto di $TDEHOME/share/apps/quanta/dtep. Nome:il nome (stringa di definizione) del DTD Pseudonimo: il nome del &DTEP; visibile all'utente Riga di definizione !DOCTYPE: la stringa che dovrà apparire nel tag !DOCTYPE, come HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd" URL DTD: l'URL che punta al file DTD Estensione predefinita: l'estensione utilizzata solitamente per i file scritti in questo DTD Tag e attributi sensibili alle minuscole/maiuscole: autoesplicativo, di solito vero per le varianti dei linguaggi XML Raffina il DTEP dopo la conversione: se selezionato, avvenuta la conversione, &quantaplus; aprirà l'editor del file &descriptionrc;, così che tu possa raffinare il &DTEP; appena creato. Si raccomanda di lasciare questa opzione selezionata.