<chapter id="extending-quanta">
<title
>&quanta; laiendamine</title>
<para
>See peatükk kirjeldab &quanta; kohandamist just sinu vajadustele, samuti seda, kuidas just sina saad aidata muuta &quanta; veel paremaks.</para>

<sect1 id="creating-quanta-docs">
<sect1info>
<author
> <firstname
></firstname
> <surname
></surname
> </author>
</sect1info>
<title
>Oma dokumentide loomine &quanta; jaoks</title>
<para
>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.</para>
<para
>Enne seda, kui asud looma omaenda dokumentatsiooni, võiksid kontrollida <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>&quanta; hoidlast</ulink
>, ega keegi juba midagi sellist teinud pole.</para>
<para
>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.</para>

<para
>Fail docrc näeb üldiselt välja umbes selline: <informalexample
> <literallayout>
#KDE Config File
[Tree]
Doc dir=&lt;dokumentatsiooni html-failide asukoht antud faili suhtes&gt; nt. php42/
#top level elements
Top Element=&lt;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
</literallayout
> </informalexample
> Fail docrc jaguneb kaheks osaks: puu ja kontekst. </para>
<para
>Puusektsioon määrab dokumentatsiooni esitamise dokumentatsiooni kaardil. Näiteks PHP dokumentide korral võid näha midagi sellist:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para
><para
>Vastavalt ülaltoodule näeb minu PHP docrc välja selline: <informalexample
> <literallayout>
#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
...

</literallayout
> </informalexample
> Pane tähele märki # kirjete <quote
>Getting Started</quote
> ja <quote
>Language Reference</quote
> 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. </para>
<para
>Sisukord (Table of Contenst) on otseviitega failile (ning seetõttu on see näha puuvaates viimasena - kataloogid esimesena!).</para>
<important
> <para
>Tühikud segavat mõju ei avalda, kuid silma peaks peal pidama märkidel &amp; ja &lt;. On tõenäoline, et kõigis XML-põhistes &quanta; ressursifailides asendatakse need vastavalt märkidega &amp;amp; ja &amp;lt;.</para
> </important>
<para
>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 <menuchoice
> <shortcut
> <keycombo action="simul"
>&Ctrl;<keycap
>H</keycap
> </keycombo
> </shortcut
> <guimenu
></guimenu
> </menuchoice
>. Ja siin ta ongi: sa näed dokumente mysql_fetch_array kohta. Siin on ainult kaht tüüpi kirjeid: ContextList ning failide seostamise read. <variablelist
> <varlistentry
> <term
>ContextList</term
> <listitem
> <para
>See on üsna lihtne, komadega eraldatud nimekiri kontekstielementidest, mis sinu tahtmist mööda peavad olema kättesaadavad (PHP puhul on need PHP funktsioonid). </para
></listitem
> </varlistentry
> <varlistentry
> <term
>Failide seostamise read</term
> <listitem
> <para
>Need on kujul kontekstielement=html dokumendi lehekülg, nt. acos=function.acos.html</para
></listitem
> </varlistentry
> </variablelist
> Kärbitud kujul näeb minu docrc kontekstisektsioon välja selline: <informalexample
> <literallayout>
#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
...
</literallayout
> </informalexample
> </para>
<para
>Nüüd võid faili docrc salvestada vastavalt sellele, kas soovid seda kasutada globaalselt või kohalikult, kataloogi <filename class="directory"
>$<envar
>KDEDIR</envar
>/share/apps/quanta/doc</filename
> või <filename class="directory"
>$<envar
>HOME</envar
>/.kde/share/apps/quanta/doc</filename
>. Seejärel loo failiga docrc samas kataloogis alamkataloog (seesama, mille määrasid failis docrc) ning kopeeri sinna oma HTML dokumendid.</para>
<para
>Kui nüüd taaskäivitad &quanta;, võidki dokumente näha.</para>
<para
>Kui oled kindel, et dokumendid on asjalikud, ning soovid neid ka teistega jagada, saada fail docrc koos kogu sinu arvates vajaliku infoga <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>&quanta; hoidlasse</ulink
>, 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.</para>

</sect1>

<sect1 id="creating-actions">
<sect1info>
<author
> <firstname
>Robert</firstname
> <surname
>Nickel</surname
> </author>
</sect1info>
<title
>Tegevuste loomine &quanta;s</title>
<para
>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 <ulink url="http://www.w3c.org/People/Raggett/tidy/"
>html tidy</ulink
>'t.</para>

<para
>Alustame siis: <menuchoice
><guimenu
>Seadistused</guimenu
><guimenuitem
>Tegevuste seadistamine</guimenuitem
></menuchoice
> </para>
<para
> 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'. </para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Me kavatseme luua uue tegevuse, nii et klõpsame nupule 'Uus' (all vasakul) ja hakkame peale.</para>

<para
>Nüüd ilmub nähtavale leht, kus saab täita järgmised tühjad väljad: <variablelist
> <varlistentry
><term
>Tekst</term
> <listitem
><para
>See on tegevuse nimi</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Kohtspikker</term
> <listitem
><para
>Ausalt öeldes ma ei tea, kas see üldse on näha. Igatahes on see lisavõimalus!</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Olekutekst</term
> <listitem
><para
>Ma ei tea, mis see on või kas see üldse näha on. Igatahes on see lisavõimalus!</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Tegevus asetatakse menüüsse (märkekast)</term
> <listitem
><para
>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 <menuchoice
><guimenu
>Seadistused</guimenu
><guimenuitem
>Tööriistaribade seadistamine</guimenuitem
></menuchoice
>.</para
></listitem
> </varlistentry
> </variablelist
> Pärast nende põhiväljade täitmist võid valida tegevusele ikooni, klõpsates sisendväljast 'Tekst' vasakul pool asuvale ikooninupule. </para>

<para
>Nüüd aga maiuspala: tegevuse definitsioon.</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Kui võtame ette märkekeele sildi defineerimise, saab selle parameetrite määramiseks kasutada kaarti 'Silt'.</para>
<para
> Põhiasi: <variablelist
> <varlistentry
> <term
>&lt;silt
></term
> <listitem
><para
>Siia saab sisestada sildi nime kujul, nagu see esineb dokumendis, nt. &lt;div align=center&gt;</para
></listitem
> </varlistentry
> <varlistentry
> <term
>&lt;/silt
></term
> <listitem
><para
>Siia saab sisestada lõpetava sildi, kui see on olemas või vajalik, või kastist märgi eemaldada, kui see puudub. Nt. &lt;/div&gt;</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Käivitatakse dialoog <quote
>Sildi muutmine</quote
> (kui võimalik)</term
> <listitem
><para
>See võimaldab käivitada dialoogiredaktori, kui antud elemendile on defineeritud sildifail. Lähemalt sildifailide kohta vaata vastavast <link linkend="tag-files"
>peatükist</link
>.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Ja nüüd... tagasi tavalisse rakendusse ning jätkame html tidy tegevuse loomist.</para>
<para
>Klõps kaardil 'Skript' toob nähtavale sellise pildi:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action2.png" format="PNG" />
</imageobject>
</inlinemediaobject
></para>
<para
> <variablelist
> <varlistentry
> <term
>Sisendikast ülal</term
> <listitem
><para
>Siia võid sisestada vajaliku käivitatava faili. Meie juhul on selleks /usr/local/bin/tidy, sest 'tidy' just seal asubki.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Nüüd sisendi/väljundi/vigade kaardid.</para>
<para
><emphasis
>Sisendikaart</emphasis
> <variablelist
> <varlistentry
> <term
>Puudub (raadionupp)</term
> <listitem
><para
>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.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Valitud tekst (raadionupp)</term
> <listitem
><para
>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...</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Käesolev dokument (raadinupp)</term
> <listitem
><para
>"Torutab" faili parajasti redaktoriaknas oleva sisu ülalolevas kastis määratud skripti standardsisendisse. See sobib juba 'tidy'-le päris hästi.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Nüüd klõpsa kaardil <emphasis
>Väljund</emphasis
>. Siin saab määrata, kuhu suunata oma skripti väljund. <variablelist
> <varlistentry
> <term
>Puudub</term
> <listitem
><para
>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.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Lisa kursori asukohta</term
> <listitem
><para
>Nii. nagu öeldud. Kontrolli, et sa asuksid ikka seal, kuhu väljundi tekst peab sinu arvates minema. 'Tidy' puhul kasutu.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Asenda käesolev dokument</term
> <listitem
><para
>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.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Loo uus dokument</term
> <listitem
><para
>Väljundiks on uus dokument redaktoriaknas. 'Tidy' puhul ilmselt parim variant.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Teadete aken</term
> <listitem
><para
>Väljund saadetakse teadete aknasse (<menuchoice
><shortcut
><keycombo action="simul"
>&Ctrl;<keycap
>M</keycap
> </keycombo
></shortcut
><guimenu
></guimenu
></menuchoice
>). See on kasulik silumisel ja vigade kaardi korral, aga mitte kaardil 'Väljund'. Ja kindlasti mitte 'tidy' puhul.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
> 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.</para>
</sect1>
</chapter>

