Capítulo 6. Escrevendo uma página de ajuda

Quando seu plugin estiver basicamente funcionando, chegou a hora de fornecer uma página de ajuda. Embora normalmente você não queira explicar todos os conceitos subjacentes em detalhes, você pode querer adicionar mais explicações para algumas das opções, e links para plugins e funções relacionados.

Você deve se lembrar de ter colocado isso dentro do seu plugin XML (se você ainda não colocou isso, faça isso agora):

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

Onde, obviamente, você substituiria nomearquivo por um nome mais apropriado. Agora é hora de criar este arquivo .rkh. Aqui está um exemplo autoexplicativo:

<!DOCTYPE rkhelp>
<document>
        <summary>
Nesta seção, você colocará algumas informações básicas e resumidas sobre o que o plugin faz. Esta seção sempre aparecerá no topo da página de ajuda.
        </summary>

        <usage>
A seção de uso pode conter informações um pouco mais práticas. Ela não explica todas as configurações
em detalhes (isso é feito na seção "configurações").

Para iniciar um novo parágrafo, insira uma linha em branco, como mostrado acima.
Esta linha, por outro lado, estará no mesmo parágrafo.

Em todas as seções, você pode inserir um código HTML simples, como <b>negrito<b> ou
texto <i>itálico<i>. Mantenha a formatação ao mínimo necessário.

A seção de uso é sempre a segunda seção exibida em uma página de ajuda.
        </usage>

        <section id="sectionid" title="Seção genérica" short_title="Genérica">
Se necessário, você pode adicionar seções adicionais entre as seções de uso e configurações.
No entanto, geralmente, você não precisará disso ao documentar plugins. O atributo "id"
fornece um ponto de ancoragem para acessar esta seção a partir do menu de navegação.
O atributo "short_title"
fornece um título curto para usar na barra de navegação. Isso é opcional. Por padrão,
o "title" principal será usado como cabeçalho da seção e como nome do link na
barra de navegação.

Em qualquer seção, você pode inserir links para mais informações. Para isso, adicione:

<link href="URL">nome do link</link>

Onde URL pode ser um link externo, como https://rkward.kde.org.

Vários URLs especiais são suportados nas páginas de ajuda:

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

Este link leva a uma página de ajuda do rkward de nível superior (não para um plugin).

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

Este link leva à página de ajuda de outro plugin. A parte [namespace/] pode ser omitida.
(neste caso, assume-se que rkward é o namespace padrão, por exemplo:
<link href="rkward://componente/import_spss"/> or
<link href="rkward://componente/rkward/import_spss"/> são equivalentes).
O id_componente é o mesmo que você especificou no .pluginmap.

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

Links para a página de ajuda do R sobre "rfunction".

Observe que os nomes dos links serão gerados automaticamente para esses tipos de links.
        </section>

        <settings>
                <caption id="id_da_aba_ou_quadro"/>
                <setting id="id_do_elemento">
Descrição do elemento da GUI identificado pelo ID fornecido
                </setting>
                <setting id="id_do_elementob" title="descrição">
Normalmente, o título do elemento da GUI será extraído da
definição XML do plugin automaticamente. Entretanto,
para alguns elementos da interface gráfica, esta descrição pode não ser suficiente para identificá-los de forma confiável.
Nesse caso, você pode adicionar um título explícito usando o atributo "title".
                </setting>
                <setting id="id_do_elementoc">
Descrição do elemento da interface gráfica identificado por "id_do_elementoc"
                </setting>
                [...]
        </settings>

        <related>
A seção "related" geralmente contém apenas alguns links, como:

<ul>
        <li><link href="rkward://rhelp/meam"/></li>
        <li><link href="rkward://rhelp/median"/></li>
        <li><link href="rkward://componente/compontente_relacionado"/></li>
</ul>
        </related>

<technical>
A seção técnica (opcional, sempre a última) pode conter alguns detalhes técnicos da implementação do plugin,
que são de interesse apenas para os desenvolvedores do RKWard. Isso é particularmente relevante
para plugins projetados para serem incorporados em muitos outros plugins e pode detalhar quais
opções estão disponíveis para personalizar o plugin incorporado e quais seções de código contêm qual
código R.
        </technical>
</document>