Capitolo 6. Scrivere una pagina della guida

Quando la propria estensione praticamente funziona, è arrivato il momento di fornire una pagina di guida. Mentre in genere non si vorranno spiegare tutti i concetti sottostanti in profondità, si potrebbe voler aggiungere qualche spiegazione in più per alcune delle opzioni e fornire collegamenti alle estensioni correlate e alle funzioni di R.

Ci si dovrebbe ricordare di inserirlo nel codice XML della propria estensione (se non è stato inserito, farlo subito):

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

Dove, ovviamente, si desidera sostituire nomefile con un nome più appropriato. Ora è il momento di creare questo file .rkh. Ecco un esempio auto-descrittivo:

<!DOCTYPE rkhelp>
<document>
        <summary>
In questa sezione, fornirete alcune brevi informazioni di base su ciò che fa l'estensione
Questa sezione sarà sempre visualizzata nella parte superiore della pagina di aiuto.
        </summary>

        <usage>
La sezione sull'utilizzo può contenere alcune informazioni più pratiche. Tuttavia, non spiega tutte
le impostazioni in dettaglio (questo è fatto nella sezione di "settings").

Per iniziare un nuovo paragrafo, inserire una riga vuota, come mostrato sopra.
Questa riga, al contrario, sarà nello stesso paragrafo.

In tutte le sezioni puoi inserire del semplice codice HTML, come <b>bold</b> o
<i>italic</i> text. Comunque, mantenere la formattazione al minimo necessario.

La sezione sull'utilizzo è sempre la seconda sezione mostrata in un pagina della guida.
        </usage>

        <section id="sectionid" title="Sezione generica" short_title="Generica">
Se necessario, è possibile aggiungere ulteriori sezioni tra le sezioni di utilizzo e impostazioni.
Tuttavia, di solito, non sarà necessario durante la documentazione delle estensioni. L'attributo «id»
fornisce un punto di ancoraggio per saltare a questa sezione dal menu di navigazione. L'attributo «short_title»
fornisce un breve titolo da utilizzare nella barra di navigazione. Questo è facoltativo, in modo predefinito
sarà utilizzato il titolo principale «title» sia come intestazione alla sezione, sia come nome del collegamento nella
barra di navigazione.

In ogni sezione potreste voler inserire dei collegamenti a ulteriori informazioni. Potete farlo aggiungendo

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

Dove URL può essere un collegamento esterno del tipo https://rkward.kde.org .
Sono supportati diversi URL speciali nelle pagine della guida:

<link href="rkward://pagina/percorso/id_pagina"/>

Questo collega a una pagina della guida di primo livello di rkward (non per un'estensione).

<link href="rkward://componente/[spazio_dei_nomi/]id_componente"/>

Questo collega alla pagina della guida di un'altra estensione. La parte [spazio_dei_nomi/] potrebbe essere omessa
(in questo caso, rkward è assunto come spazio dei nomi standard, ad es.:
<link href="rkward://componente/importa_spss"/> o
<link href="rkward://componente/rkward/importa_spss"/> sono equivalenti).
L'id_componente è lo stesso che hai specificato nella .pluginmap.

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

Collega alla pagina della guida di R per «rfunction».

Notare che i nomi dei collegamenti saranno generati automaticamente per questi tipi di collegamenti.
        </section>

        <settings>
                <caption id="id_scheda_o_cornice"/>
                <setting id="id_elemento">
Descrizione dell'elemento della GUI identificato dall'ID specificato
                </setting>
                <setting id="id_elementob" title="descrizione">
Normalmente, il titolo dell'elemento della GUI sarà estratto dalla
definizione XML dell'estensione, automaticamente. Tuttavia,
per alcuni elementi della GUI, questa descrizione potrebbe non essere sufficiente per identificarli, in modo affidabile.
In questo caso, potete aggiungere un titolo esplicito utilizzando l'attributo «title».
                </setting>
                <setting id="id_elementoc">
Descrizione dell'elemento della GUI identificato da «id_elementoc»
                </setting>
                [...]
        </settings>

        <related>
La sezione relativa tipicamente contiene solo alcuni elementi, come:

<ul>
        <li><link href="rkward://rhelp/mean"/></li>
        <li><link href="rkward://rhelp/median"/></li>
        <li><link href="rkward://componente/componente_relativo"/></li>
</ul>
        </related>

        <technical>
La sezione tecnica (facoltativa, sempre ultima) può contenere alcuni dettagli tecnici dell'implementazione
dell'estensione, che sono d'interesse solo per gli sviluppatori di RKWard. Questo è particolarmente rilevante
per le estensioni che sono progettate per essere integrate in altre estensioni, e può dettagliare quali
opzioni sono disponibili per personalizzare l'estensione integrata, e quali sezioni di codice contengono quale
codice di R.
        </technical>
</document>