# &quanta; laiendamine

See peatükk kirjeldab &quanta; kohandamist just sinu vajadustele, samuti seda, kuidas just sina saad aidata muuta &quanta; veel paremaks.

## Oma dokumentide loomine &quanta; jaoks

Võib-olla üks tavakasutajale kõige silmatorkavamaid lisandusi &quanta;s on võimalus lisada dokumentatsiooni endale meelepärase märgistus- või skriptikeele kohta. See peatükk selgitab, kuidas luua PHP dokumentatsioonipuu isiklikuks kasutamiseks.

Enne seda, kui asud looma omaenda dokumentatsiooni, võiksid kontrollida &quanta; hoidlast, ega keegi juba midagi sellist teinud pole.

Loomisprotsess koosneb kahest osast. Esiteks tuleb hankida. selle märgistus/skripti/misiganes keele olemasolev dokumentatsioon. Teiseks tuleb luua docrc fail. Esimene jääb su enda ülesandeks, teist asume järgnevalt kirjeldama.

Fail docrc näeb üldiselt välja umbes selline:

    #KDE Config File
    [Tree]
    Doc dir=<dokumentatsiooni html-failide asukoht antud faili suhtes> nt. php42/
    #top level elements
    Top Element=<nende dokumentide kirjeldus
    > nt. 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

Fail docrc jaguneb kaheks osaks: puu ja kontekst.

Puusektsioon määrab dokumentatsiooni esitamise dokumentatsiooni kaardil. Näiteks PHP dokumentide korral võid näha midagi sellist:

Vastavalt ülaltoodule näeb minu PHP docrc välja selline:

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

Pane tähele märki # kirjete Getting Started ja Language Reference ees. See näitab, et need on omaette ühikud puus, millel on omaenda sisu. Ma ei usu, et puu sügavusele oleks kusagil limiit seatud (kui jätta arvestamata kaine mõistuse määratu) - nii et kasuta siin oma paremat äranägemist.

Sisukord (Table of Contenst) on otseviitega failile (ning seetõttu on see näha puuvaates viimasena - kataloogid esimesena!).

Tühikud segavat mõju ei avalda, kuid silma peaks peal pidama märkidel & ja <. On tõenäoline, et kõigis XML-põhistes &quanta; ressursifailides asendatakse need vastavalt märkidega &amp; ja &lt;.

Kontekstisektsioon on docrc osa, mida kasutatakse kontekstitundliku abi jaoks. Näiteks võid PHP skripti kirjutades soovida näha dokumente funktsiooni mysql_fetch_array kohta. Tõsta funktsioon esile ning vajuta seejärel kontekstiabi saamiseks &Ctrl;H . Ja siin ta ongi: sa näed dokumente mysql_fetch_array kohta. Siin on ainult kaht tüüpi kirjeid: ContextList ning failide seostamise read.

ContextList

- See on üsna lihtne, komadega eraldatud nimekiri kontekstielementidest, mis sinu tahtmist mööda peavad olema kättesaadavad (PHP puhul on need PHP funktsioonid).

Failide seostamise read

- Need on kujul kontekstielement=html dokumendi lehekülg, nt. acos=function.acos.html

Kärbitud kujul näeb minu docrc kontekstisektsioon välja selline:

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

Nüüd võid faili docrc salvestada vastavalt sellele, kas soovid seda kasutada globaalselt või kohalikult, kataloogi `$`KDEDIR`/share/apps/quanta/doc` või `$`HOME`/.kde/share/apps/quanta/doc`. Seejärel loo failiga docrc samas kataloogis alamkataloog (seesama, mille määrasid failis docrc) ning kopeeri sinna oma HTML dokumendid.

Kui nüüd taaskäivitad &quanta;, võidki dokumente näha.

Kui oled kindel, et dokumendid on asjalikud, ning soovid neid ka teistega jagada, saada fail docrc koos kogu sinu arvates vajaliku infoga &quanta; hoidlasse, kus neid saab kasutada ka ülejäänud &quanta; kogukond. See ei tee sind küll rikkaks, kuid laseb tunda heameelt, et oled andnud oma panuse parimasse olemasolevasse veebiarendusplatvormi.

Robert Nickel

## Tegevuste loomine &quanta;s

Tegevused kujutavad &quanta;s alust peaaegu kõigile laiendustele, mida &quanta; praegu või tulevikus kasutab. Sama mehhanism, mis defineerib &quanta;s tegevusi, võimaldab automaatset lõpetamist ning sildidialooge. Tegevuste puhul sisuliselt puuduvad piirangud. Näitena kasutame siinkohal meie veebilehtedel html tidy't.

Alustame siis: Seadistused Tegevuste seadistamine

Tegevuste dialoogi käivitamisel peaks ilmuma selline aken. Vasakul asub nimekiri praegu teadaolevate tegevustega. Sa võid neist mõne välja valida ning sooritada samasugused sammud, mida meie võtame ette oma tegevusega 'html tidy'.

Me kavatseme luua uue tegevuse, nii et klõpsame nupule 'Uus' (all vasakul) ja hakkame peale.

Nüüd ilmub nähtavale leht, kus saab täita järgmised tühjad väljad:

Tekst

- See on tegevuse nimi

Kohtspikker

- Ausalt öeldes ma ei tea, kas see üldse on näha. Igatahes on see lisavõimalus!

Olekutekst

- Ma ei tea, mis see on või kas see üldse näha on. Igatahes on see lisavõimalus!

Tegevus asetatakse menüüsse (märkekast)

- Selle märkimine võimaldab kasutada hüpikmenüüd, kus saab valida tööriistariba, kuhu tegevus paigutada. Kui sa seda praegu ei vali, saad seda teha ka hiljem menüükäsuga Seadistused Tööriistaribade seadistamine.

Pärast nende põhiväljade täitmist võid valida tegevusele ikooni, klõpsates sisendväljast 'Tekst' vasakul pool asuvale ikooninupule.

Nüüd aga maiuspala: tegevuse definitsioon.

Kui võtame ette märkekeele sildi defineerimise, saab selle parameetrite määramiseks kasutada kaarti 'Silt'.

Põhiasi:

<silt >

- Siia saab sisestada sildi nime kujul, nagu see esineb dokumendis, nt. <div align=center>

</silt >

- Siia saab sisestada lõpetava sildi, kui see on olemas või vajalik, või kastist märgi eemaldada, kui see puudub. Nt. </div>

Käivitatakse dialoog Sildi muutmine (kui võimalik)

- See võimaldab käivitada dialoogiredaktori, kui antud elemendile on defineeritud sildifail. Lähemalt sildifailide kohta vaata vastavast peatükist.

Ja nüüd... tagasi tavalisse rakendusse ning jätkame html tidy tegevuse loomist.

Klõps kaardil 'Skript' toob nähtavale sellise pildi:

Sisendikast ülal

- Siia võid sisestada vajaliku käivitatava faili. Meie juhul on selleks /usr/local/bin/tidy, sest 'tidy' just seal asubki.

Nüüd sisendi/väljundi/vigade kaardid.

Sisendikaart

Puudub (raadionupp)

- Skript ei kasuta üldse sisendit. See võib olla kasulik, kui kutsud näiteks välja Tcl/Tk skripti, mis avab hüpikakna, kus kasutaja saab midagi teha, ning seejärel annab kasutajale teada tulemused. 'Tidy' jaoks valime aga midagi muud.

Valitud tekst (raadionupp)

- Täpselt nii, nagu öeldud: parajasti valitud teksti koopia saadetakse ülalolevas kastis määratud skripti standardsisendisse. Seda võiks ka tidy puhul kasutada, aga pole sugugi lõbus suures dokumendis muudkui valida ja valida ja valida ja...

Käesolev dokument (raadinupp)

- "Torutab" faili parajasti redaktoriaknas oleva sisu ülalolevas kastis määratud skripti standardsisendisse. See sobib juba 'tidy'-le päris hästi.

Nüüd klõpsa kaardil Väljund. Siin saab määrata, kuhu suunata oma skripti väljund.

Puudub

- Nojah, eks ta võib ju tore olla, kui käivitad mõne välise rakenduse, mis võtab ainult vastu, aga ei anna midagi tagasi. 'Tidy' puhul seda küll mõtet kasutada ei ole.

Lisa kursori asukohta

- Nii. nagu öeldud. Kontrolli, et sa asuksid ikka seal, kuhu väljundi tekst peab sinu arvates minema. 'Tidy' puhul kasutu.

Asenda käesolev dokument

- Tähendab täielikku faili asendamist. See ei kirjuta küll kettal faili üle, aga parajasti redigeeritav seanss asendatakse küll. Kasuta seda ettevaatlikult. Meie igatahes 'tidy' puhul seda ei kasuta.

Loo uus dokument

- Väljundiks on uus dokument redaktoriaknas. 'Tidy' puhul ilmselt parim variant.

Teadete aken

- Väljund saadetakse teadete aknasse (&Ctrl;M ). See on kasulik silumisel ja vigade kaardi korral, aga mitte kaardil 'Väljund'. Ja kindlasti mitte 'tidy' puhul.

Kaardil 'Viga' on valida samasuguste võimaluste vahel, nagu äsjakirjeldatud väljundikaardil. Enamasti kasutatakse siin väljundi saatmist teadete aknasse, et hõlbustada vigade leidmist ja parandamist, või siis jäetakse väljund üldse valimata.