&quantaplus; uitbreiden

Christopher Hornbaker

    chrishornbaker@earthlink.net

András Mantia

    amantia@kde.org

&Sander.Koning;&Tom.Albers;

# &quantaplus; uitbreiden

Dit hoofdstuk beschrijft hoe u &quantaplus; aan uw eigen wensen kunt aanpassen en hoe u kunt helpen &quantaplus; te verbeteren.

## Document Type Editing Package (&DTEP;)

Document Type Editing Packages (&DTEP;'s) worden in &quantaplus; gebruikt om ondersteuning voor opmaak- en scripttalen en &CSS; te bieden. Ze zorgen ervoor dat &quantaplus; auto-aanvulling en 'node'-boomstructuren kan bieden. Omdat ze eenvoudig en flexibel zijn, is &quantaplus; een snelle en gebruiksvriendelijke &IDE; voor webontwikkelaars. Ze zorgen ervoor dat &quantaplus; een eenvoudig te gebruiken en productieve omgeving is.

Er zijn twee soorten &DTEP;'s. 'Family 1' voor opmaak en 'Family 2' voor scripting en &CSS;. &DTEP;'s bestaan uit twee delen: de Tagmap en de Werkbalken. Tagmappen bestaan op hun beurt uit twee soorten bestanden: het bestand &descriptionrc; en TagXML-bestanden met de extensie .tag. Werkbalken zijn de handige pictogrambalken (boven het editorvenster) die tekst in een document kunnen plaatsen sneller dan de gebruiker kan typen.

&DTEP;'s kunnen handmatig worden gemaakt (zie onder), gedownload worden, of automatisch worden aangemaakt vanuit een bestaande DTD. Zie voor details over deze omzetting.

Dit document beschrijft hoe u TagXML-bestanden, het bestand &descriptionrc; en werkbalken maakt. Kortweg een &DTEP;.

TagXML-bestanden (.tag) definiëren de attributen die specifiek voor een tag zijn en de opmaak en inhoud van het eigenschappenvenster dat &quantaplus; voor de tag opent. Het bestand bevat regels &descriptionrc;en informatie voor de &DTEP; zelf. Werkbalken bieden een snelle mogelijkheid om tags in een document in te voegen zonder angst voor typefouten en dergelijke.

### Bundelen

Tagmappen zijn eigenlijk gewoon mappen. Ze bestaan echter alleen uit het bestand en de TagXML-&descriptionrc;bestanden. De naam van een tagmap geeft de opmaaktaal en de gebruikte versie daarvan aan. Bijvoorbeeld html-4.01-strict.

### TagXML

De onderstaande tabel geeft een overzicht van de elementen die in TagXML gedefinieerd zijn en of deze verplicht zijn of niet. Hoewel niet alle elementen verplicht zijn, wordt het aanbevolen dat u er zo veel mogelijk gebruikt, opdat andere gebruikers er beter mee kunnen werken.

Element | Standaardgebruik | Gebruik
--- | --- | ---
TAGS | verplicht | altijd
tag | verplicht | altijd
label | optioneel | verplicht voor het aanmaken van een eigenschappenvenster
attr | optioneel | verplicht voor het definiëren van een attribuut
tooltip | optioneel | verplicht als het eigenschappenvenster een hulpballon moet weergeven
whatsthis | optioneel | verplicht als het eigenschappenvenster een Wat is dit? moet weergeven
list | optioneel | verplicht als een attribuut van het type list is
item | optioneel | verplicht als <list > gebruikt wordt
textlocation | optioneel | altijd
location | optioneel | verplicht als label gebruikt wordt
text | optioneel | verplicht als label gebruikt wordt
children | optioneel | lijst met tags die binnen de gedefinieerde tag gebruikt kunnen worden
child | verplicht | een children-item
stoppingtags | optioneel | lijst met tags waardoor een andere tag gesloten wordt
stoppingtag | verplicht | een stoppingtags-item

#### Beschrijving van de TagXML-elementen

De volgende secties beschrijven elk element in detail. Alles, van waar ze gebruikt kunnen worden tot wat ze kunnen bevatten, wordt op een eenvoudige manier aangegeven.

##### TAGS

Dit is het basiselement van een TagXML-document. Het mag slechts één keer in een document voorkomen. Het kan meerdere tagdefinities bevatten. Dit element kan alleen andere elementen bevatten.

Bovenliggende items | Subitems
--- | ---
GEEN | tag

##### tag

Omliggende definitie van de tag. Dit element kan alleen andere elementen bevatten.

Bovenliggende items | Subitems
--- | ---
TAGS | label, attr, stoppingtags

Attribuut | Type | Waarden | Standaard | Gebruik | Beschrijving
--- | --- | --- | --- | --- | ---
name | string |  |  | verplicht | De naam van de tag.
single | boolean |  |  | optioneel | Geeft aan of de tag een sluittag (</tagnaam >) vereist.
type | string |  | xmltag | optioneel | Het type van de tag.
|  | xmltag |  |  | Het type van de tag is XML-gebaseerd (alleen Family 1).
|  | entiteit |  |  | De tag beschrijft een entiteit (alleen Family 1).
|  | property |  |  | Het type van de tag is &CSS;-gerelateerd (alleen Family 2).
|  | function |  |  | Het type van de tag is een scriptfunctie. In dit geval worden <attr> als argumenten van de functie gebruikt. (Alleen Family 2.)
|  | class |  |  | Het type van de tag is een scriptklasse. (Alleen Family 2.)
|  | method |  |  | Het type van de tag is een klassemethode. (Alleen Family 2.)
returnType | string |  | void | optioneel | Het 'returntype' van de tag.
|  | void |  |  | Het type retourneert void.
|  | int |  |  | Het type retourneert een int.
|  | float |  |  | Het type retourneert een float.
|  | long |  |  | Het type retourneert een long.
|  | string |  |  | Het type retourneert een string.
version | string |  |  | optioneel | Geeft de versie van de taal aan waarvoor deze tag geldig is
extends | string |  |  | optioneel | Alleen geldig als het type van de tag "class" is. De naam van de basisklasse voor deze klasse. (Alleen Family 2).
class | string |  |  | optioneel | Alleen geldig als het type "method" is. De naam van de basisklasse voor deze methode. (Alleen Family 2).
common | boolean |  |  | optioneel | bij "ja" specificeert de tag een gemeenschappelijke attribuutgroep en kunnen de attributen in deze tag op elke andere tag toegepast worden. (Alleen Family 1.)
comment | string |  |  | optioneel | De commentaar-tekenreeks verschijnt bij de tagnaam in het aanvullingskader.

##### label

Plaats een label in het dialoogvenster. De tekst wordt aangegeven in de tag <text>. Dit element kan alleen andere elementen bevatten.

Bovenliggende items | Subitems
--- | ---
tag | text, location

##### attr

Geeft een attribuut van de tag aan. Voor elk attribuut wordt dit element opgegeven, dat de naam en het type van het attribuut aangeeft. Het bevat tevens tags die bijvoorbeeld aangeven hoe het attribuut moet worden weergegeven. In dit element kunnen alleen andere elementen voorkomen.

Bovenliggende items | Subitems
--- | ---
tag | location, list, tooltip, whatsthis, textlocation

Attribuut | Type | Waarden | Standaard | Gebruik | Beschrijving
--- | --- | --- | --- | --- | ---
name | string |  |  | verplicht | Geeft de naam van het attribuut aan.
type | string |  | input | verplicht | Geeft het type van het attribuut aan.
|  | input |  |  | Het veld ondersteunt willekeurige tekst (tekstveld).
|  | check |  |  | De veldwaarde is een boolean (selectievakje).
|  | color |  |  | De veldwaarde is een kleur.
|  | url |  |  | De veldwaarde is een &URL; (lokaal bestand om naar te verwijzen).
|  | list |  |  | De veldwaarde is een item van een opgegeven lijst.
status | string |  | optioneel | verplicht | Geeft aan of het argument wel of niet verplicht is (alleen Family 2).
|  | optioneel |  |  | Het argument is optioneel.
|  | verplicht |  |  | Het argument is verplicht.
|  | implied |  |  | Het argument is impliciet.
bron | string |  |  | optioneel | Specificeert de bronnen die gebruikt worden om het attribuut in te vullen in het editor-dialoogvenster en de attributen-boomstructuur.
|  | selection |  |  | De geselecteerde tekst wordt als bron gebruikt
|  | dcop |  |  | Het resultaat van een DCOP-methode wordt als bron gebruikt.
interface | string |  |  | optioneel | Vereist source="dcop". De DCOP-interface vanuit &quantaplus; die gebruikt wordt om de brondata te verkrijgen.
method | string |  |  | optioneel | Vereist source="dcop" en een interfacenaam. De DCOP-methodenaam vanuit &quantaplus; die gebruikt wordt om de brondata te verkrijgen.
argumenten | string |  |  | optioneel | Vereist source="dcop", een interface en een methodenaam. De argumenten die aan de methode worden meegegeven. Dit kan leeg zijn of "%tagname%" voor de nam van de huidige tag.

##### tooltip

Definieert de tekstballon voor een veld in het dialoogvenster. Dit element kan alleen tekst bevatten.

Op het moment wordt alleen platte tekst ondersteund (u kunt geen opmaak gebruiken).

Bovenliggende items | Subitems
--- | ---
attr | GEEN

##### whatsthis

Definieert de 'Wat is dit'-hulptekst voor een veld in het dialoogvenster. Dit element kan alleen tekst bevatten.

Op het moment wordt alleen platte tekst ondersteund (u kunt geen opmaak gebruiken).

Bovenliggende items | Subitems
--- | ---
attr | GEEN

##### list

Een tag die de items samenvoegt in een lijst. Kan slechts één keer voorkomen per attribuutbeschrijving. Dit element kan alleen andere elementen bevatten.

Bovenliggende items | Subitems
--- | ---
attr | item

##### item

Definieert een item in een lijst. In dit element kan alleen tekst voorkomen.

Bovenliggende items | Subitems
--- | ---
list | GEEN

##### textlocation

Geeft de positie van de attribuuttekst van de tekst aan in een dialoogvenster. Deze tag kan slechts één keer per attribuut in het dialoogvenster voorkomen (&ie; één keer per <attr > tag). Dit element is leeg (kan niets bevatten).

Bovenliggende items | Subitems
--- | ---
attr | GEEN

Attribuut | Type | Gebruik | Beschrijving
--- | --- | --- | ---
row | nonNegativeInteger | verplicht | Geeft de rij in de dialoogopmaak van een veld of label aan.
col | nonNegativeInteger | verplicht | Geeft de kolom in de dialoogopmaak van een veld of label aan.
rowspan | nonNegativeInteger | optioneel | Geeft het aantal rijen aan dat een veld moet overspannen.
colspan | nonNegativeInteger | optioneel | Geeft het aantal kolommen aan dat een veld moet overspannen.

##### location

Geeft de positie en grootte van een veld in het dialoogvenster aan. Deze tag dient één keer per veld in het dialoogvenster voor te komen (één keer voor elke <attr> of <label> tag). Dit element is leeg (kan niets bevatten).

Bovenliggende items | Subitems
--- | ---
label, attr | GEEN

Attribuut | Type | Gebruik | Beschrijving
--- | --- | --- | ---
row | nonNegativeInteger | verplicht | Geeft de rij in de dialoogopmaak van een veld of label aan.
col | nonNegativeInteger | verplicht | Geeft de kolom in de dialoogopmaak van een veld of label aan.
rowspan | nonNegativeInteger | optioneel | Geeft het aantal rijen aan dat een veld moet overspannen.
colspan | nonNegativeInteger | optioneel | Geeft het aantal kolommen aan dat een veld moet overspannen.

##### text

Geeft de tekst voor een label of selectievakje aan. Dit element kan alleen tekst bevatten.

Bovenliggende items | Subitems
--- | ---
label, attr | GEEN

##### children

Geeft een lijst van elementen aan die binnen de tag kunnen voorkomen. In dit element kunnen alleen andere elementen voorkomen.

Bovenliggende items | Subitems
--- | ---
tag | child

##### child

Definieert een subtag. Dit element is leeg.

Bovenliggende items | Subitems
--- | ---
children | GEEN

Attribuut | Type | Waarden | Gebruik | Beschrijving
--- | --- | --- | --- | ---
name | string |  | verplicht | Geeft een tag aan die binnen een andere tag kan voorkomen.
gebruik | string |  | optioneel | Geeft de relatie met de bovenliggende tag aan.
|  | verplicht |  | De bovenliggende tag moet minstens één kind met deze naam hebben.

##### stoppingtags

Geeft een lijst met elementen aan die het einde van een tag dwingen. In dit element kunnen alleen andere elementen voorkomen.

Bovenliggende items | Subitems
--- | ---
tag | stoppingtag

##### stoppingtag

Geeft een beëindigende tag aan. Dit element is leeg.

Bovenliggende items | Subitems
--- | ---
stoppingtags | GEEN

Attribuut | Type | Gebruik | Beschrijving
--- | --- | --- | ---
name | string | verplicht | Geeft aan welke tags het einde van een andere tag afdwingen.

#### Het gebruik van TagXML

Alle TagXML-bestanden moeten beginnen met de &XML;-declaratie: <?xml version="1.0" encoding="UTF-8"?> en moeten correct genest en gesloten zijn.

U kunt veilig witruimte gebruiken, maar let wel op de tekens & en <. Deze dient u te vervangen door &amp; respectievelijk &lt; in elementen als <tooltip >, <whatsthis > en <text >. Als u dit niet doet zal er geen crash optreden, maar u zult wel delen van uw werk verliezen.

#### Validatie van TagXML

Om uw TagXML-bestanden te valideren kiest u Gereedschap bovenaan het venster van &quantaplus; en kiest u daar Valideren. Er verschijnt een dialoogvenster waarin u alleen maar de aanwijzingen hoeft op te volgen.

Op het moment is deze functie nog niet aanwezig. Validatie vindt nu plaats op het moment dat een TagXML-bestand in &quantaplus; wordt ingeladen.

#### Voorbeelden van TagXML

##### Family 1

Hieronder ziet u een geldig Family 1-TagXML-bestand. Dit bestand beschrijft &W3C; &XML; Schema's element <schema >. De bestandsnaam van dit fragment zou schema.tag zijn. Simpel, nietwaar?

    <?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
    >Een uniek ID-nummer voor het element.</tooltip>
       <whatsthis
    >Een uniek ID-nummer voor het element.</whatsthis>
       <location col="1" row="0"/>
      </attr>

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

      <label>
       <text
    >targetNamespace</text>
       <location col="0" row="2"/>
      </label>
      <attr name="targetNamespace" type="input">
       <tooltip
    >&URI;-verwijzing naar de namespace van dit schema.</tooltip>
       <whatsthis
    >&URI;-verwijzing naar de namespace van dit schema.</whatsthis>
       <location col="1" row="2"/>
      </attr>

      <label>
       <text
    >xmlns</text>
       <location col="0" row="3"/>
      </label>
      <attr name="xmlns" type="input">
       <tooltip
    >&URI;-verwijzing naar een of meerdere namespaces om in dit schema te gebruiken.
       Als geen voorvoegsel is opgegeven, mogen componenten van de betreffende namespace ongekwalificeerd gebruikt worden.</tooltip>
       <whatsthis
    >&URI;-verwijzing naar een of meerdere namespaces om in dit schema te gebruiken.
       Als geen voorvoegsel is opgegeven, mogen componenten van de betreffende namespace ongekwalificeerd gebruikt worden.</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
    >Standaardvorm voor alle atrributen in dit schema.</tooltip>
       <whatsthis
    >Standaardvorm voor alle attributen in dit 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
    >Standaardvorm voor alle elementen in dit schema.</tooltip>
       <whatsthis
    >Standaardvorm voor alle elementen in dit 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>

##### Family 2

Hieronder vindt u een geldig Family 2-TagXML-bestand. Dit fragmentbeschrijft &PHP;'s functie overload. De bestandsnaam hiervoor zou overload.tag zijn.

    <?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;

Het bestand &descriptionrc; is ook redelijk eenvoudig en er is een editor voor beschikbaar vie DTD DTD-instellingen bewerken. Hiermee bewerkt u de &descriptionrc; voor een &DTEP; die u uit een lijst kunt kiezen. Om de &descriptionrc; voor een nieuwe &DTEP; te bewerken is het handig om een eenvoudige &descriptionrc; te maken met het volgende:

            [General]
            Version = Gebruik 1 voor &quantaplus; versie <=3.1.2 en 2 voor een nieuwere versie.
            Name = DTD-definitie. (-//&W3C;//DTD HTML 4.01 Transitional//EN)
            NickName = De mooier gemaakte naam van de DTD. (HTML 4.01 Transitional). Als dit niet opgegeven is wordt Name
            gebruikt als NickName.

Als u deze aangemaakt hebt en naast de tagbestanden hebt geplaatst, laadt u de nieuw aangemaakte &DTEP; emt DTD DTD-pakket (DTEP) laden en nadat deze ingeladen is kunt u doorgaan met het wijzigen van de instellingen van de &DTEP;. Kijk naar de ballonhulp en de "watisdit"-teksten in het editor-dialoogvenster om de betekenis van elk item te begrijpen. U kunt ook het bestand `quanta/data/dtep/dtd-description.txt` uit het bron-tar-archief lezen dat een beschrijving van het formaat bevat.

## Gebruiker-gedefinieerde acties

Acties komen veel in toepassingen vaak voor. U komt ze vaak tegen als u een toepassing gebruikt. Op een werkbalkpictogram klikken, een menu-item selecteren of een sneltoets gebruiken voert normaal gesproken een actie uit. In &quantaplus; worden acties op een hoger niveau geplaatst. In plaats van acties die door de programmeur van de applicatie vastgelegd zijn, kan de gewone gebruiker acties aanmaken en bewerken, en op deze manier nieuwe functionaliteit aan &quantaplus; toevoegen. Veel standaardacties binnen &quantaplus; zijn gebruiker-gedefinieerd en u kunt deze dan ook zelf bewerken.

Er zijn drie soorten gebruiker-gedefinieerde acties:

- Tekstacties

- Tagacties

- Scriptacties

### Acties aanmaken

U kunt een actie aanmaken via Instellingen Acties instellen. Klik op Nieuwe actie en u krijgt een vergelijkbaar dialoogvenster:

Type

  Geeft het type aan (tekst-, tag-, script-).

Tekst

  De naam van de actie zoals de gebruiker die ziet.

De knop naast het label Tekst

  Het pictogram voor deze actie. Klik op het pictogram om het te wijzigen.

Scherminfo

  Korte beschrijving van wat de actie doet.

Sneltoets

  De sneltoets die aan deze actie wordt toegewezen. Klik op Aangepast of de knop bij Aangepast om een sneltoets toe te wijzen, klik op Geen om de huidige sneltoets te verwijderen.

Containerbalken

  De gebruikergedefinieerde werkbalken waar deze actie voorkomt. Zie .

Gedetailleerde instellingen

  Specifieke instellingen voor de verschillende soorten acties. Zie hieronder.

### Tekstacties

De eenvoudigste acties. U kunt tekst invoeren onderGedetailleerde instellingen en als de actieuitgevoerd wordt, wordt die tekst in uw document op de huidigecursorpositie ingevoegd. Zie hieronder voor een voorbeeld.

### Tagacties

Nuttig om XML-tags in te voegen, maar u kunt ze natuurlijk ook voor andere doelen gebruiken.

<tag>

  De naam van de tag.

</tag>

  Als de actie wordt uitgevoerd, wordt deze tekst als sluittag ingevoegd. Als er een gebied in uw document geselecteerd is op het moment dat de actie wordt uitgevoerd, wordt <tag> voor, en </tag> na het geselecteerde gebied geplaatst.

Dialoogvenster "Tag bewerken" starten indien beschikbaar

  Als er een tagXML-bestand voor deze tag beschikbaar is, wordt er een dialoogvenster getoond waarin u de tag kunt bewerken, voordat de tag daadwerkelijk wordt ingevoegd.U kunt de attributen van de tag zo handmatig bewerken.

<tag> en </tag> worden ingevoegd zoals u hier opgeeft. <, > of / wordt niet automatisch toegevoegd.

### Scriptacties

Het krachtigste soort acties. Met behulp van deze acties kunt u externe toepassingen uitvoeren (normaliter scripts, maar andere applicaties zijn ook mogelijk), die (een deel van) uw document kunnen bewerken of gebruiken als invoer. Voorbeelden uit &quantaplus; zelf zijn het dialoogvenster Snelstarten en de diverse Tonen in... acties voor (X)HTML DTEP's.

Voer eerst de naam van uw script in, inclusief de interpreter. Bijvoorbeeld `sh /home/mijnmap/mijnscript.sh`.

Hoewel u volledige paden kunt gebruiken, wordt het aanbevolen om de variabele `%scriptdir` te gebruiken, zoals in `sh %scriptmap/mijnscript.sh`. &quantaplus; zal dan uw script op de volgende locaties zoeken:

- globale scriptmap: ``$KDEDIR`/share/apps/quanta/scripts`

- lokale scriptmapr: ``$KDEHOME`/share/apps/quanta/scripts`

- uw pad: `$PATH`

Verder kunt u de volgende speciale variabelen in de opdrachtregel gebruiken:

- `%f`: wordt vervangen door de URL van het huidige document. Als u een lokaal document aan het bewerken bent zal het voorvoegsel file:/ weggehaald worden.

- `%input`: wordt vervangen door de geselecteerde invoer. Zie hieronder.

- `%projectbase`: wordt vervangen door de URL van het huidige project (is leeg als er geen project geladen is).

- `%pid`: wordt vervangen door het PID van het huidige&quantaplus;-proces. Als &quantaplus; in unieke modus wordt uitgevoerd, wordt de tekst "unique " voorgevoegd aan het PID-getal.Dit is nuttig als u DCOP gebruikt om &quantaplus; vanuit externe scripts aan te sturen.

- `%userarguments`: nuttig in het geval van gebeurtenissen. Dit wordt vervangen door de eigenschappen van de gebeurtenis, in deze volgorde:

  Eerste argument

    Het unieke id van het script

  Tweede argument

    de gebeurtenisnaam

  Derde argument

    de parameters voor de gebeurtenis, normaal de bestandsnaam van het huidige document of het pad naar het projectbestand.

Naast de bovenstaande methodes kan het script ook invoer van &quantaplus; ontvangen via standaardinvoer. In de keuzelijst Invoer kunt u kiezen wat er via standaardinvoer aan het script verzonden moet worden. U kunt kiezen uit:

- Geen: er wordt niets verzonden.

- Huidig document: het gehele document wordt verzonden.

- Geselecteerde tekst: het geselecteerde gebied in het doucment wordt naar het script verzonden. De variabele `%input` is meestal alleen nuttig als u deze optie kiest.

Analoog aan het sturen van Invoer kunt u ook de uitvoer van de uitgevoerde applicatie ontvangen. Er zijn twee soorten uitvoer:

- normale uitvoer (via standaarduitvoer);

- foutmeldingen (via standaardfoutuitvoer).

U kunt opgeven wat er met de teruggegeven uitvoer moet gebeuren. Dit doet u door de waarde van de keuzelijst Uitvoer aan te passen:

- Geen: de uitvoer wordt genegeerd.

- Bij cursorpositie invoegen: de uitvoer wordt op de huidige cursorpositie in het document ingevoegd.

- Selectie vervangen: het geselecteerde gebied in hetdocument wordt vervangen door de uitvoer.

- Selectie vervangen: het geselecteerde gebied in hetdocument wordt vervangen door de uitvoer.

- Nieuw document aanmaken: een nieuw document wordt aangemaakt dat de uitvoer van het script bevat.

- Huidig document vervangen: de volledige inhoud van het huidige document wordt vervangen door de uitvoer.

- Berichtenvenster: de uitvoer verschijnt in het venster Berichten.

Voor de standaardfoutuitvoer (Fout) kunt u dezelfde keuzes maken als voor de gewone uitvoer.

## Werkbalken aanmaken

Het volgende deel laat u zien hoe u werkbalken voor een &DTEP; aanmaakt. Werkbalken zijn grafische elementen die aan acties worden toegewezen.In &quantaplus; vormen acties de basis voor bijna alle uitbreidingendie in &quantaplus; beschikbaar zijn of zullen worden. Hetzelfdemechanisme dat een actie in &quantaplus; definieert, maakt ook autoaanvulling en tagdialoogvensters mogelijk. U kunt met acties bijna alles doen wat u wilt. Als voorbeeld gebruiken we &HTML; tidy op onze webpagina's.

### Van niets tot een geheel

Als eerste hebt u een gebruiker-werkbalk nodig. Kies Werkbalken Gebruiker-werkbalk toevoegen .

Als er veel tags in de opmaaktaal zitten, wordt het aanbevolen dat u de tags in logische groepen verdeelt. Voor elke groep is dan een nieuwe gebruiker-werkbalk benodigd. In dit geval zijn er niet veel tags, dus maken we één werkbalk en geven die de naam van de opmaaktaal.

Nadat uw werkbalken aangemaakt zijn, moeten er acties worden toegevoegd en ingesteld. Kies hiervoor Instellingen Acties instellen .

Dit venster is redelijk zelfverklarend. Kies Nieuwe actie onderaan het venster om over te schakelen naar de bewerkmodus.

Vul alle verplichte velden in en voeg de tag toe aan de gewenste werkbalk(en).

Vul de overige velden in, en als de tag attributen bevat die u telkens wilt gebruiken, activeert u Dialoogvenster "Tag bewerken" starten indien beschikbaar.

U zou nu iets moeten hebben dat erg op het volgende lijkt.

Klik op de knop Toepassen en u zult de actietoegevoegd zien aan de werkbalk(en) die u gekozen had.

Hmmm... dat is een afschuwelijk pictogram. Hoe kunnen u en anderen onthouden welke actie er bij welk pictogram hoort? Laten we het vervangen voordat er problemen ontstaan.

Om een pictogram te maken dat de actie nauwkeuriger weergeeft, maken we gebruik van &kiconedit;. Start dit via het &kmenu;, Grafisch Meer programma's (of waar uw distributie het ook geplaatst heeft).

&kiconedit; maakt standaard pictogrammen van 32x32 pixels, maar wij hebben 22x22 nodig. Verander dit met Bewerken Grootte wijzigen .

Onthoud dat u een pictogram maakt dat niet alleen uzelf eraanherinnert welke actie erbij hoort, maar ook andere gebruikers van de &DTEP;.

Omdat de tag waar ik een pictogram voor nodig heb start heet, heb ik besloten om een start-teken te maken. Met de kleur groen (die veel gebruikt wordt voor gaan, starten of doorgaan) zal de gebruiker snel zien dat dit de tag <start> in het huidige document plaatst. (Althans, dat is de bedoeling.)

Nu het pictogram klaar is, sla ik het op.

Als u klaar bent met het aanmaken van uw pictogram(men), moet het pictogram nog aan de actie gekoppeld worden. Kies hiervoor Instellingen Acties instellen (in &quantaplus;) en selecteer de actie waarvoor het pictogram bedoeld is. Naast het veld Tekst bevindt zich een knop. Klik daarop.

Kies Andere pictogrammen en vervolgens Bladeren.

Ga naar de map waarin u het pictogram hebt opgeslagen, selecteer het pictogram en klik OK.

Kies Toepassen en doe hetzelfde voor de andere tags (voorzover die er zijn), of kies OK om af te sluiten.

Laten we zeggen dat u een aantal veelgebruikte functies uit &quantaplus; aan uw werkbalk wilt toevoegen, of misschien wilt u de werkbalk op een andere manier indelen, met een paar scheidingen om de acties te groeperen. Open het dialoogvenster Werkbalken instellen via Instellingen Werkbalken instellen . Zorg ervoor dat uw werkbalk geselecteerd is.

Ik voeg een scheiding (bovenaan de linkerkolom) toe aan mijn werkbalk. Als u het item hebt geselecteerd dat u aan uw werkbalk wilt toevoegen, klikt u op de pijl naar rechts. Hiermee voegt u het toe.

Ik wil graag een snelle manier om het voorbeeld in Konqueror te bereiken. Ik voeg het daarom aan de werkbalk toe.

Merk op hoe de scheiding de groepen aangeeft. Iemand die mijn werkbalk niet kent, zou misschien kunnen denken dat de &konqueror;-knop iets te maken had met de startknop.

Pas de wijzigingen toe, en klik als u klaar bent op OK om af te sluiten.

Ah, kijk eens naar die werkbalk. Zo is hij een stuk handiger.

Vergeet niet uw werkbalk te testen door alle knoppen een keer uit te proberen, zodat u weet dat de uitvoer correct is.

Om de werkbalk op te slaan kiest u Werkbalken Werkbalken opslaan Als lokale werkbalk opslaan .

Sla in de juiste map op. Omdat NeXML niet bestaat, sla ik het maar in de hoofdmap op, maar uw werkbalk(en) moet(en) in de goede map opgeslagen worden. Zorg ervoor dat u uw &descriptionrc; aanpast zodat uw werkbalken geladen worden als een nieuw bijbehorend bestand aangemaakt wordt.

Uw eigen documentatie maken

Robert Nickel

    robert@artnickel.com

&Sander.Koning;&Tom.Albers;

## Uw eigen documentatie maken

Waarschijnlijk is de meest opvallende toevoeging aan &quantaplus; voor de gewone gebruiker, het toevoegen van documentatie voor de opmaak- of scripttaal die u het beste bevalt. Hiertoe laat dit hoofdstuk zien hoe ik de &PHP;-documentatieboom voor mijn eigen gebruik aanmaak.

Voordat u uw eigen documentatie maakt, is het wellicht handig om op de &quantaplus; repository te kijken of iemand anders dit set misschien al gedaan heeft.

Dit proces bestaat uit twee delen. Eerst moet u de bestaande documentatie voor de opmaak-/script-/&etc; taal ophalen. Daarna moet het bestand `docrc` aangemaakt worden. We beschrijven hier alleen het tweede deel.

Het bestand docrc ziet er als volgt uit:

    #KDE Config File
    [Tree]
    Doc dir=pad, relatief aan dit bestand, naar de html-bestanden van de documentatie ⪚ php42/
    #top level elements
    Top Element=Uw beschrijving van deze documentatie ⪚ &PHP; 4.2 documentation

    Section 1=Section1.html
    Section 2=#Sec2.1,#Sec2.2,#Sec2.3
    Sec2.1=Sec2.1.html
    Sec2.2=Sec2.2.html
    Sec2.3=Sec2.3.html
    ...

    [Context]
    ContextList=func1,func2,tag1,tag2,tag3
    func1=func1.html
    func2=func2.html
    tag1=tag1.html
    tag2=tag2.html
    tag3=tag3.html

Het bestand `docrc` is verdeeld in twee secties: Tree en Context.

De sectie Tree bepaalt het uiterlijke aspect van de documentatie in de documentatie-tab. Bijvoorbeeld, in de documentatie van &PHP; zult u iets als dit hebben:

We combineren dit met het bovenstaande: mijn &PHP; `docrc` ziet er als volgt uit:

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

Let op de `#` voor Getting Started en Language Reference. Dit geeft aan dat deze subcontainers zijn die zelf inhoud hebben. Er is geen vastgesteldemaximale diepte — gebruik uw gezond verstand.

U zult merken dat naar de inhoudsopgave direct als bestand wordtverwezen en dus onderaan de boomstructuurweergave verschijnt (mappen eerst!).

Spaties vormen geen probleem, maar kijk uit voor de tekens & en <. Vervang deze door &amp; respectievelijk &lt; in alle &XML;-gebaseerde bestanden in &quantaplus;.

De sectie Context is het deel van het bestand docrc dat context-gevoelige hulp biedt. Bijvoorbeeld: u schrijft een &PHP;-script en wilt de documentatie voor de functie`mysql_fetch_array` zien. U selecteert defunctie en drukt dan &Ctrl;H voor contexthulp. De documentatie voor `mysql_fetch_array` verschijnt direct. Er zijn hier maar twee soorten items: ContextList en de regels met bestandsassociaties.

ContextList

  Dit is slechts een door komma's gescheiden lijst van de contextitems die u ter beschikking wilt hebben (voor &PHP; zijn dit de &PHP;-functies).

Regels met bestandsassociaties

  Deze zijn opgebouwd als context-item=html-bestand. ⪚ acos=function.acos.html

Een verkleinde versie van de sectie Context in mijn bestand `docrc` ziet er als volgt uit:

    #Keywords for context help
    [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
    ...

Sla nu uw bestand `docrc` op in de directory`$`HOME`/.kde/share/apps/quanta/doc` of `$`KDEDIR`/share/apps/quanta/doc` voor lokaal respectievelijk globaal gebruik. Maak dan een map aan zoals u die in hetbestand `docrc` hebt opgegeven, in dezelfde map als waar het bestand `docrc` zich bevindt, en kopieer daar uw &HTML;-pagina's heen.

U dient &quantaplus; opnieuw op te starten om uw documentatie te kunnen lezen.

Als u er zeker van bent dat ze goed zijn en de moeite van het delen waard,stuur dan uw bestand `docrc` samen met wat informatie over de documentatie die u gebruikt heeft, naar het &quantaplus; repository opdat de rest van de &quantaplus; gemeenschap er ook gebruik van kan maken. U zult niet rijk worden, maar wel een goed gevoel krijgen in de wetenschap dat u heeft bijgedragen aan het beste webontwikkelingsplatform dat er is.

## Bronnen delen

Met &quantaplus; bent u niet alleen. Het is mogelijk om de diverse bronnen (DTEP-pakketten, werkbalken met acties, scripts, sjablonen) te delen met anderen. Hier zijn twee manieren voor:

Per e-mail verzenden

  U kunt de bronnen per e-mail naar uw vrienden, partners, of wie u ook wilt, verzenden. U komt het menu-item Via e-mail verzenden op diverse plaatsen tgen, zoasl DTD DTD-pakket (DTEP) via e-mail zenden, Werkbalken Werkbalk via e-mail verzenden, in het contextmenu van de bestanden en mappen in de boomstructuren Werkbalken en Scripts.

Naar de hoofdserver uploaden

  De bronnen kunnen naar onze hoofd-repository worden verzonden, waarvandaan alle andere gebruikers van &quantaplus; ze kunnen downloaden. De inzendingen worden gecontroleerd en alleen beschikbaar gesteld als ons team ze correct en bruikbaar vindt. Om een geldige inzending te hebben, wordt het aanbevolen om de bronnen te ondertekenen, waarvoor u een GPG/PGP-sleutel nodig hebt. Deze informatie wordt door ons team en de downloaders gebruikt om de oorsprong van de bronnen te controleren.

  Zie over het verkrijgen van bronnen van de hoofdserver.

  Als u bestanden verzendt, wordt u gevraagd het wachtwoord voor uw geheime GPG-sleutel in te voeren (het wachtwoord wordt niet opgeslagen), of als u meer dan één sleutel hebt, kunt u degene kiezen die u wilt gebruiken. In het dialoogvenster Leuk nieuw spul delen vult u de invoervelden in (Voorbeeld-URL mag leeg blijven) en u start het verzenden door op OK te klikken.

  Verzenden kan worden gestart met DTD DTD-pakket (DTEP) uploaden, Werkbalken Werkbalk uploaden, in het contextmenu van bestanden en mappen in de boomstructuren voor Sjablonen en Scripts.

## Bronnen verkijgen

U kunt &quantaplus; bijwerken zonder een nieuwe versie te hoeven installeren, door nieuwe bronnen als DTEP-pakketten, werkbalken met acties, sjablonen, scripts en documentatie te verkrijgen. Een mogelijkheid is dat u de bronnen per e-mail hebt ontvangen of dat u ze hebt gedownload vanaf een webserver, in welke gevallen u ze normaal gesproken handmatig moet installeren. In een enkel geval krijgt u er ook een installatiescript bij, als u geluk hebt. Maar &quantaplus; biedt een toegewijde server die bronnen bevat die ofwel niet werden meegeleverd vanwege de grootte of infrequent gebruik, of doordat ze later door gebruikers zijn aangeboden, en deze worden automatisch geïnstalleerd. Download zulke bronnen via de diverse menu-items downloaden.... U vindt deze in DTD DTD-pakket (DTEP) downloaden, Werkbalken Werkbalk downloaden, in het contextmenu van een leeg gebied of bovenste item in de structuurbomen van Sjablonen, Scripts en Documentatie.

Nadat een bron gedownload is, maar voordat deze geïnstalleerd wordt, verifieert &quantaplus; of de bron geldig is, door de integriteit en handtekening te controleren. Bij problemen wordt u gewaarschuwd en kunt u beslissen om al dan niet door te gaan. Lees de waarschuwingsdialogen zorgvuldig. Als de integriteit correct is en de bron goed ondertekend is, krijgt u een informatievenster, waarin u kunt zien wie de bron gemaakt heeft.

Installeer bronnen, met name werkbalken en scripts, alleen vanaf vertrouwde locaties!

## Een DTD naar een &DTEP; omzetten

Het is mogelijk om met XML-talen te werken die momenteel niet door &quantaplus; worden ondersteund door een DTEP-pakket te maken. Maar het aanmaken hiervan kan veel tijd kosten, omdat u wellicht honderden tagbestanden in tagXML-formaat moet schrijven. Er is hier een betere manier voor, namelijk het automatisch omzetten van de DTD in een DTEP-pakket.

U kunt de omzetting starten met DTD DTD laden & converteren. Kies het `.dtd`-bestand waarin de te gebruiken DTD staat, u ziet daarna het volgende dialoogvenster:

De items zijn:

- Naam doelmap: de nieuwe &DTEP; wordt onder deze naam in de map ``$KDEHOME`/share/apps/quanta/dtep` opgeslagen.

- Naam: de naam (definitie-tekenreeks) van de DTD

- Nickname: de voor de gebruiker zichtbare naam van de &DTEP;

- !DOCTYPE definitieregel: de tekenreeks die in de tag !DOCTYPE moet verschijnen, zoals HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"

- DTD URL:: het URL-adres van het DTD-bestand

- Standaard extensie: de extensie die normaal gebruikt wordt voor bestanden met deze DTD

- Hoofdlettergevoelige tags en attributen: zelfverklarend, over het algemeen geldig voor XML-taalvarianten

- DTEP fijn aanpassen na conversie: als dit is aangevinkt, opent &quantaplus; de &descriptionrc;-editor nadat de conversie gedaan is, zodat u de nieuwe &DTEP; kunt aanpassen. Dit wordt aanbevolen.