Kapitel 6. Skriva en hjälpsida

När insticksprogrammet i grund och botten fungerar, är det dags att tillhandahålla en hjälpsida. Även om man typiskt inte vill förklara alla bakomliggande koncepten från grunden, kanske du vilja lägga till några fler förklaringar för vissa av alternativen, och länka till relaterade insticksprogram och R-funktioner.

Du kanske minns att du lagt till det här i insticksprogrammets XML (om du inte har det, lägg till det nu):

<document>
        [...]
        <help file="filnamn.rkh" />
        [...]
</document>
        

Där du naturligtvis ersätter filnamn med ett lämpligare namn. Nu är det dags att skapa .rkh-filen. Här är ett självbeskrivande exempel:

<!DOCTYPE rkhelp>
<document>
        <summary>
I det här avsnittet skriver man in kort, mycket grundläggande information om vad insticksprogrammet gör.
Avsnittet visas alltid allra längst upp på hjälpsidan.
        </summary>

        <usage>
Sektionen usage kan innehålla lite mer praktisk information. Den ska dock inte förklara
alla inställningarna i detalj (det görs i sektionen "settings").

Infoga en ny rad för att påbörja ett nytt stycke, som visas ovan.
I motsats till det, ingår den här raden i samma stycke.

Enkel HTML-kod kan infogas i alla avsnitt, såsom text med <b>fetstil</b> eller
<i>kursiv stil</i>. Använd dock helst minimal formatering som är nödvändig.

Avsnittet usage är alltid det andra avsnittet som visas på en hjälpsida.
        </usage>

        <section id="sectionid" title="Generic section" short_title="Generic">
Om det behövs, kan ytterligare avsnitt läggas till mellan avsnitten usage och settings.
Dock behövs det oftast inte när insticksprogram dokumenteras. Egenskapen "id"
tillhandahåller en ankringspunkt för att gå till avsnittet i navigeringsmenyn. Egenskapen "short_title"
tillhandahåller en kort rubrik att använda i navigeringsraden. Den är valfri, normalt
använd "title" både som rubrik för avsnittet, och som länknamnet i
navigeringsraden.

Man kan vilja infoga länkar till ytterligare information i vilket avsnitt som helst. Det gör man genom att lägga till

<link href="webbadress">länknamn</link>

Där webbadress skulle kunna vara en extern adress som http://rkward.kde.org .
Flera speciella webbadresser stöds i hjälpsidorna:

<link href="rkward://sida/sökväg/sid-id"/>

Länkar till en rkward hjälpsida på toppnivå (inte för ett insticksprogram).

<link href="rkward://component/[namnrymd/]komponent-id"/>

Länkar till hjälpsidan för ett annat insticksprogram. Delen [namnrymd/] kan utelämnas
(i så fall, antas rkward som standardnamnrymd, exempelvis är
<link href="rkward://component/import_spss"/> och
<link href="rkward://component/rkward/import_spss"/> ekvivalenta).
Komponent-id är samma som anges av .pluginmap.

<link href="rkward://rhelp/r-funktion"/>

Länkar till R-hjälpsidan om "r-funktion".

Observera att länknamn skapas automatiskt för följande typer av länkar.
        </section>

        <settings>
                <caption id="id_of_tab_or_frame"/>
                <setting id="id_of_element">
Beskrivning av elementet i det grafiska användargränssnittet identifierat av angivet id
                </setting>
                <setting id="id_of_elementb" title="description">
Oftast extraherar rubriken för elementet i det grafiska användargränssnittet automatiskt från
insticksprogrammets XML-definition. Dock
kanske beskrivningen inte är nog för att tillförlitligt identifiera dem för vissa element i det grafiska användargränssnittet.
I så fall kan en explicit rubrik läggas till med egenskapen "title".
                </setting>
                <setting id="id_of_elementc">
Beskrivning av elementet i det grafiska användargränssnittet identifierat av "id_of_elementc"
                </setting>
                [...]
        </settings>

        <related>
Avsnittet related innehåller oftast bara några länkar, såsom:

<ul>
        <li><link href="rkward://rhelp/mean"/></li>
        <li><link href="rkward://rhelp/median"/></li>
        <li><link href="rkward://component/related_component"/></li>
</ul>
        </related>

        <technical>
Avsnittet technical (valfritt, alltid sist) kan innehålla några tekniska detaljer om insticksprogrammets
implementering, som bara är av intresse för utvecklare av RKWard. Det är särskilt relevant
för insticksprogram som är konstruerade för att inbäddas i många andra insticksprogram, och kan ange vilka
alternativ är tillgängliga för att anpassa det inbäddade insticksprogrammet, och vilka kodsektioner som innehåller vilken
R-kod.
        </technical>
</document>