Capítol 6. Escriure una pàgina d'ajuda

Quan el vostre connector funciona bàsicament, ha arribat el moment de proporcionar una pàgina d'ajuda. Encara que normalment no voldreu explicar tots els conceptes subjacents en profunditat, és possible que vulgueu afegir alguna explicació més per a alguna de les opcions, i enllaçar amb connectors relacionats i funcions de l'R.

Potser recordareu posar això dins del connector XML (si no l'heu posat, feu-ho ara):

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

On, òbviament, substituireu filename per un nom més apropiat. Ara és el moment de crear aquest fitxer .rkh. Aquest és un exemple autodescriptiu:

<!DOCTYPE rkhelp>
<document>
        <summary>
En aquesta secció, posareu informació breu i molt bàsica sobre què fa el connector.
Aquesta secció sempre es mostrarà a la part superior de la pàgina d'ajuda.
        </summary>

        <usage>
La secció d'ús pot contenir una mica més d'informació pràctica. Però
no explica tots els paràmetres en detall (això es fa a la secció «settings»).

Per a iniciar un paràgraf nou, inseriu una línia buida, com es mostra a dalt.
Aquesta línia, en canvi, serà al mateix paràgraf.

En totes les seccions podeu inserir codi HTML senzill, com ara el text <b>bold</b> o <i>italic</i>. No obstant això, manteniu el format al mínim necessari.

La secció d'ús és sempre la segona secció que es mostra en una pàgina d'ajuda.
        </usage>

        <section id="sectionid" title="Secció genèrica" short_title="Genèrica">
Si cal, podeu afegir seccions addicionals entre les seccions d'ús i de configuració.
No obstant això, normalment no ho necessitareu mentre documenteu els connectors.
L'atribut «id» proporciona un punt d'ancoratge per a saltar a aquesta secció
des del menú de navegació. L'atribut «short_title» proporciona un títol curt per a utilitzar a la barra de navegació.
Això és opcional, per defecte el "títol" principal s'utilitzarà tant com a encapçalament de la secció, com a nom de l'enllaç a la barra de navegació.

En qualsevol secció podeu inserir enllaços per a més informació. Ho feu afegint

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

A on URL pot ser un enllaç extern com https://rkward.kde.org .
Es permeten diversos URL especials a les pàgines d'ajuda:

<link href="rkward://page/path/page_id"/>

Això enllaça a una pàgina d'ajuda de nivell superior del RKWard (no per a un connector).

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

Això enllaça a la pàgina d'ajuda d'un altre connector. La part [namespace/] es pot ometre
(en aquest cas, s'assumeix el RKWard com a espai de noms estàndard, p. ex.:
<link href="rkward://component/import_spss"/> o
<link href="rkward://component/rkward/import_spss"/> són equivalents).
El «component_id» és el mateix que heu especificat en el .pluginmap.

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

Enllaça a la pàgina d'ajuda "rfunction" de l'R .

Tingueu en compte que els noms dels enllaços es generaran automàticament per a aquests tipus d'enllaços.
        </section>

        <settings>
                <caption id="id_of_tab_or_frame"/>
                <setting id="id_of_element">
Descripció de l'element de la IGU identificat per l'id indicat
                </setting>
                <setting id="id_of_elementb" title="descripció">
Normalment el títol de l'element de la IGU s'extraurà a partir de la
definició XML del connector, automàticament. Tanmateix,
per a alguns elements de la IGU aquesta descripció pot no ser suficient per a identificar-los amb fiabilitat.
En aquest cas podeu afegir un títol explícit usant l'atribut "title".
                </setting>
                <setting id="id_of_elementc">
Descripció de l'element de la IGU identificat per "id_of_elementc"
                </setting>
                [...]
        </settings>

        <related>
La secció de relacions normalment conté diversos enllaços, com ara:

<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>
La secció tècnica (opcional, sempre l'última) pot contenir alguns detalls tècnics de la implementació del connector,
que només són d'interès per als desenvolupadors del RKWard. Això és particularment rellevant
per als connectors que estan dissenyats per a ser incrustats en molts altres connectors,
i podria detallar quines opcions estan disponibles per a personalitzar el connector incrustat,
i quines seccions de codi contenen quin codi R.
        </technical>
</document>