<chapter id="extending-quanta">
<title
>Utöka &quanta;</title>
<para
>Det här kapitlet beskriver hur &quanta; kan anpassas till just dina behov, och hur du kan hjälpa till att göra &quanta; bättre.</para>

<sect1 id="creating-quanta-docs">
<sect1info>
<author
> <firstname
></firstname
> <surname
></surname
> </author>
</sect1info>
<title
>Skapa egna dokument för &quanta;</title>
<para
>Troligen är de mest anmärkningsvärda tilläggen till &quanta; för den vanliga användaren, tillägg av dokumentation för de tagg- eller skriptspråk som är mest omtyckta. Med detta syfte, förklarar det här kapitlet hur jag skapar PHP-dokumentationsträdet för min egen användning.</para>
<para
>Innan du börjar skapa din egen dokumentation, vill du kanske titta på <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>&quanta;s arkiv</ulink
> för att se om någon redan har gjort den här uppsättningen.</para>
<para
>Det finns två delar i processen. Först måste du skaffa befintlig dokumentation för taggspråket, skriptspråket eller något annat språk som du är ute efter. Därefter måste du skapa docrc-filen. Det första får du klara själv, det andra är vad vi täcker här.</para>

<para
>Den allmänna formen för docrc-filen är följande: <informalexample
> <literallayout>
#KDE konfigurationsfil
[Tree]
Doc dir=&lt;sökväg, relativt denna filen, till dokumentationens HTML-filer&gt; t.ex. php42/
#toppnivåelement
Top Element=&lt;Din beskrivning av de här dokumenten
> t.ex. PHP 4.2 dokumentation

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
> Filen docrc är uppdelad i två avdelningar: Tree (träd) och Context (Sammanhang). </para>
<para
>Avdelningen Tree definierar presentationsaspekter för dokumentet under dokumentationsfliken. Du ser till exempel att i PHP-dokumentationen, har du något som liknar det här:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para
><para
>Med referens till ovanstående, ser min PHP docrc ut så här: <informalexample
> <literallayout>
#KDE konfigurationsfil

[Tree]

Doc dir=php42/

#toppnivåelement
Top Element=PHP 4.2 dokumentation

PHP 4.2 dokumentation=Innehållsförteckning,#Komma igång,#Språkreferens

Innehållsförteckning=index.html

Komma igång=Inledning, ...
Inledning=introduction.html
...

Språkreferens=Grundläggande syntax, ...
Grundläggande syntax=language.basic-syntax.html
...

</literallayout
> </informalexample
> Observera # framför <quote
>Komma igång</quote
> och <quote
>Språkreferens</quote
>. Det anger att de är delinnehåll i trädet och har eget innehåll. Jag tror inte det finns en angiven gräns för djupet här (utom det som dikteras av sunt förnuft) - använd din egen bedömning. </para>
<para
>För innehållsförteckningen, ser du att den direkt refererar till en fil (och som en konsekvens, visas den längst ner i trädvyn, kataloger kommer först).</para>
<important
> <para
>Mellanslag påverkar ingenting negativt, men se upp med tecknen &amp; och &lt;. Dessa ska troligen ersättas med &amp;amp; och &amp;lt; i alla &quanta;s XML-baserade resursfiler.</para
> </important>
<para
>Avdelningen Context är den del av docrc-filen som används för att möjliggöra sammanhangsberoende hjälp. Om du till exempel skriver ett PHP-skript, och vill se dokumentationen för funktionen mysql_fetch_array. Du markerar helt enkelt funktionen och trycker <menuchoice
> <shortcut
> <keycombo action="simul"
>&Ctrl;<keycap
>H</keycap
> </keycombo
> </shortcut
> <guimenu
></guimenu
> </menuchoice
> för sammanhangsberoende hjälp, Svisch! Du ser dokumentationen för mysql_fetch_array. Det finns bara två typer av poster här: ContextList och filsambandsraderna. <variablelist
> <varlistentry
> <term
>ContextList</term
> <listitem
> <para
>Mycket enkel, det här är bara en lista separerad med kommatecken av sammanhangsposterna som du vill ha tillgängliga (för PHP är det dess funktioner). </para
></listitem
></varlistentry
> <varlistentry
><term
>Filsambandsrader</term
><listitem
><para
>De här är på formen Sammanhangspost=HTML-dokumentationssida, t.ex. acos=function.acos.html</para
></listitem
></varlistentry
></variablelist
> En nerbantad version av avdelningen Context från min docrc-fil är följande: <informalexample
> <literallayout>
#Nyckelord för sammanhangsberoende hjälp
[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
>Nu kan du bara spara din docrc-fil. Spara den i <filename class="directory"
> $<envar
>HOME</envar
>/.kde/share/apps/quanta/doc</filename
> eller <filename class="directory"
> $<envar
>KDEDIR</envar
>/share/apps/quanta/doc</filename
> för lokal eller global användning. Skapa sedan en katalog (den som anges i docrc-filen) i samma katalog som docrc-filen finns, och kopiera HTML-dokumentationssidorna dit.</para>
<para
>Du måste starta om &quanta;, och då ser du dina egna dokument.</para>
<para
>När du väl är säker på att de är bra, och värda att dela, skicka docrc-filen tillsammans med en beskrivning av passande information om vilka dokument du använde till <ulink url="http://quanta.sourceforge.net/main1.php?contfile=resource"
>&quanta;s arkiv</ulink
> för användning av &quanta;s gemenskap. Du blir inte rik, men du känner dig nöjd med vetskap om att du bidragit till den bästa webbutvecklingsmiljön som finns.</para>

</sect1>

<sect1 id="creating-actions">
<sect1info>
<author
> <firstname
>Robert</firstname
> <surname
>Nickel</surname
> </author>
</sect1info>
<title
>Skapa åtgärder i &quanta;</title>
<para
>Åtgärder i &quanta; är grunden för nästan alla utökningar som &quanta; har, och kommer att få i framtiden. Samma mekanism som definierar en åtgärd i &quanta; aktiverar automatisk komplettering och taggdialogrutor. Med åtgärder är gränserna för vad du kan göra näst intill obegränsade. Som ett exempel, använder vi <ulink url="http://www.w3c.org/People/Raggett/tidy/"
>html tidy</ulink
> från våra webbsidor.</para>

<para
>Låt oss börja: <menuchoice
><guimenu
>Inställningar</guimenu
> <guimenuitem
>Anpassa åtgärder</guimenuitem
></menuchoice
> </para>
<para
> När du väl har startat åtgärdsdialogrutan ser du det här fönstret. Till vänster är listan med för närvarande kända åtgärder. Du kan markera en av dem och utföra samma saker med en befintlig åtgärd, som vi ska göra med vår åtgärd "html tidy". </para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Vi ska skapa en ny åtgärd, så låt oss klicka på knappen Ny (nere till vänster) och börja.</para>

<para
>Nu visas ett tomt antal alternativ att fylla i: <variablelist
><varlistentry
><term
>Text</term
><listitem
><para
>Det här är namnet på åtgärden</para
></listitem
></varlistentry
> <varlistentry
><term
>Verktygstips</term
> <listitem
><para
>Vet inte säkert var detta visas. Det är valfritt!</para
></listitem
> </varlistentry
><varlistentry
><term
>Statustext</term
> <listitem
><para
>Vet inte vad detta är till för eller var det används. Det är valfritt!</para
></listitem
></varlistentry
><varlistentry
> <term
>Placera åtgärden på (kryssruta)</term
><listitem
><para
>Det här aktiverar kombinationsrutan för att välja en verktygsrad där den här åtgärden ska placeras. Om du inte väljer nu, kan du alltid lägga till den senare med <menuchoice
><guimenu
>Inställningar</guimenu
> <guimenuitem
>Anpassa verktygsrader</guimenuitem
></menuchoice
>.</para
></listitem
></varlistentry
></variablelist
> Efter att ha fyllt i de här grundläggande sakerna, kan du välja en ikon för åtgärden genom att klicka på ikonknappen till vänster om inmatningsrutan 'Text'. </para>

<para
>Nu till själva kärnan. Definitionen av åtgärden.</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action1.png" format="PNG" />
</imageobject>
</inlinemediaobject>
</para>
<para
>Om vi höll på att definiera en tagg, kunde vi här använda fliken tagg för att skriva in taggens parametrar.</para>
<para
> Alltså: <variablelist
> <varlistentry
> <term
>&lt;tag
></term
> <listitem
><para
>Det är här du skriver in taggnamnet som det syns i dokumentet, t.ex. &lt;div align=center&gt;.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>&lt;/tag
></term
> <listitem
><para
>Det är här du skriver in den avslutande taggen, om det finns någon, eller avmarkera rutan om ingen finns, t.ex. &lt;/div&gt;.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Kör dialogen för <quote
>Redigera tagg</quote
> om den finns</term
> <listitem
><para
>Det här kör dialogeditorn om det finns en taggfil definierad för det här objektet. Titta i avsnittet om <link linkend="tag-files"
>taggfiler</link
>, för mer information om taggfiler.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Och nu ... Tillbaka till det vanliga programmet i tablån. Vi fortsätter med att skapa åtgärden "html tidy".</para>
<para
>Klicka på fliken Skript för att visa följande:</para>
<para
><inlinemediaobject>
<imageobject>
<imagedata fileref="conf-action2.png" format="PNG" />
</imageobject>
</inlinemediaobject
></para>
<para
> <variablelist
> <varlistentry
> <term
>inmatningsruta längst upp</term
> <listitem
><para
>Här skriver du in det körbara programmet som du är ute efter. I vårt fall skulle det vara /usr/local/bin/tidy, eftersom det är där jag har lagt programmet tidy.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Nu fortsätter vi med flikarna Inmatning, Utmatning och Fel.</para>
<para
><emphasis
>Fliken Inmatning</emphasis
> <variablelist
> <varlistentry
> <term
>Inget (radioknapp)</term
> <listitem
><para
>Använd ingen inmatning för skriptet. Det kan vara användbart om du anropade ett TCL/TK-skript som visade ett fönster för användaren, och sedan returnerade sitt resultat. Vi väljer något annat för tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Markerad text (radioknapp)</term
> <listitem
><para
>Precis vad det säger. Det skickar en kopia av aktuell markerad text till standardinmatningen för skriptet i inmatningsrutan ovan. Vi skulle kunna använda det för tidy, men det är inget roligt att behöva markera allt i ett stort dokument.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Aktuellt dokument (radioknapp)</term
> <listitem
><para
>Skickar innehållet i editorns version av filen till standardinmatningen för skriptet i inmatningsrutan ovan. Det är vad vi använder för tidy.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
>Klicka nu på fliken <emphasis
>Utmatning</emphasis
>. Det är här vi bestämmer vart skriptets utmatning ska skickas. <variablelist
> <varlistentry
> <term
>Inget</term
> <listitem
><para
>Så dumt. Det här skulle vara bra om du startade ett externt program som bara tar emot indata, men inte skriver ut någonting. Det är inte särskilt användbart för oss med tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Infoga på markörens plats</term
> <listitem
><para
>Precis vad som sägs. Försäkra dig om att du står där du vill att texten ska infogas. Inte bra för tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Ersätt aktuellt dokument</term
> <listitem
><para
>Fullständig ersättning av filen här. Det skriver inte över filen på disk, men förstör den nuvarande redigeringssessionen. Använd med försiktighet. Vi använder inte detta för tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Skapa nytt dokument</term
> <listitem
><para
>Mata ut till ett nytt dokument i redigeringsfönstret. Det här är det bästa valet för tidy.</para
></listitem
> </varlistentry
> <varlistentry
> <term
>Meddelandefönster</term
> <listitem
><para
>Utmatning till meddelandefönstret <menuchoice
><shortcut
><keycombo action="simul"
>&Ctrl;<keycap
>M</keycap
> </keycombo
></shortcut
><guimenu
></guimenu
></menuchoice
>. Det är användbart för avlusning och fliken Fel, men inte för mycket annan utmatning. Inte bra för tidy.</para
></listitem
> </varlistentry
> </variablelist
> </para>
<para
> För fliken Fel, är alternativen samma som för fliken Utmatning. Oftast använder man meddelandefönstret, för att hjälpa till med avlusning, eller alternativet Inget.</para>
</sect1>
</chapter>