Hoofdstuk 6. Een help-pagina schrijven:

Als uw plugin in principe werkt, komt het moment dat u een help-pagina gaat maken. U wilt wellicht niet alle onderliggende concepten uitputtend uit de doeken doen, maar wel enige uitleg geven over sommige opties, en koppelen aan gerelateerde plugins en functies in R.

U kunt zich misschien herinneren dat u dit in uw plugin-XML plaatste (als u dit nog niet heeft gedaan, doe het nu):

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

Waarin u, natuurlijk, bestandsnaam vervangt door de juiste naam. Het is nu tijd het .rkh-bestand aan te maken. Hier volgt een voorbeeld dat voor zichzelf spreekt:

<!DOCTYPE rkhelp>
<document>
        <summary>
In deze sectie plaatst u wat erg korte basisinformatie over het doel van uw plugin.
Deze sectie staat altijd helemaal bovenaan in de helppagina.
        </summary>

        <usage>
De gebruikssectie kan wat meer praktische informatie bevatten. Niet alle instellingen worden tot in detail uitgelegd (maar dat gebeurt in de sectie “instellingen”).

U kunt een nieuwe alinea beginnen met een lege regel, zoals u hierboven ziet.
Deze regel, daarentegen, is in dezelfde alinea.

In alle secties kunt u eenvoudige HTML-code invoegen, zoals <b> bold</b> of
<i>italic</i> text. Maar beperk dit formatteren tot het minimum nodige.

De gebruikssectie is altijd de tweede sectie in de help-pagina.
        </usage>

        <section id="sectionid" title="Algemene sectie" short_title= "Algemeen">
Indien nodig kunt u secties toevoegen tussen de secties voor gebruiken instellingen.
Maar voor het documenteren van plugins heeft u dit gewoonlijk niet nodig. Het“id”-attribuut
geeft een ankerpunt voor het springen naar deze sectie vanuit het navigatiemenu.Het "short_title"
attribuut geeft een korte naam voor in de navigatiebalk. Dit is optioneel, standaard
wordt de hoofd"naam" gebruikt, zowel als kopnaam voor de sectie, als voor de naam van de koppeling
in de navigatiebalk.

In elke sectie kunt u koppelingen invoegen naar verdere informatie. U doet dit met het toevoegen van

<link href="URL">link name</link>

Waarin URL een externe koppeling kan zijn zoals http://rkward.kde.org .
Enkele speciale URL’s worden in de help-pagina’s ondersteund:

<link href="rkward://pagina/pad/pagina_id"/>

Dit koppelt naar een topniveau help-pagina in rkward (geen plugin).

<link href="rkward://component/[namespace/]component_id"/>

Dit koppelt naar de help-pagina van een andere plugin. Het [namespace/] deel kan worden weggelaten
(in dit geval wordt rkward aangenomen als standaard namespace, bv.:
<link href="rkward://component/import_spss"/> of
<link href="rkward://component/rkward/import_spss"/> zijn equivalent).
De component_id is dezelfde als die u opgaf in de .pluginmap.

<link href="rkward://rhelp/rfunction"/>

Kopppelt naar de help-pagina van R voor "rfunction".

Merk op dat de namen van de koppelingen van dit type koppelingen automatisch worden gegenereerd.
        </section>

        <settings>
                <caption id="id_of_tab_or_frame"/>
                <setting id="id_of_element">
Beschrijving van het GUI-element behorend bij de gegeven id
                </setting>
                <setting id="id_of_elementb" title="beschrijving">
Gewoonlijk komt de naam van het GUI-element automatisch uit de
XML-definitie van de plugin, Maar
voor sommige GUI-elementen is deze beschrijving onvoldoende voor betrouwbare identificatie.
In dat geval kunt u een expliciete naam toevoegen met het “title”-attribuut.
                </setting>
                <setting id="id_of_elementc">
Beschrijving van het GUI-element behorend bij "id_of_elementc"
                </setting>
                [...]
        </settings>

        <related>
De bijbehorende sectie bevat typisch slechts enkele koppelingen, zoals:

<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>
De technische sectie (optioneel, altijd laatst) kan wat technische details over de implementatie van
de plugin bevatten, die alleen van belang zijn voor RKWard-ontwikkelaars. Dit is vooral van belang bij
plugins, die in veel andere plugins moeten worden ingebed, en kunnen vermelden welke opties
er zijn voor het aanpassen van de ingebedde plugins, en welke codesectieswelke
R code bevatten.
        </technical>
</document>