Розділ 6. Створення сторінки довідки

Оскільки додаток, загалом, вже працює як слід, наспів час створити для нього сторінку довідки. Хоча, зазвичай, вам не варто пояснювати кожен раз усе з початку, було б добре надати певні відомості щодо деяких з параметрів та посилання на пов’язані додатки і функції R.

Вам варто додати це до коду XML вашого додатка (якщо ви цього ще не зробили, зробіть це зараз):

<document>
        [...]
        <help file="назва_файла.rkh" />
        [...]
</document>
        

Де, очевидно, вам слід замінити вираз назва_файла на відповідну назву. Тепер, створимо цей файл .rkh. Ось приклад із наведеними в ньому описами:

<!DOCTYPE rkhelp>
<document>
        <summary>
У цьому розділі мають бути основні відомості щодо того, які завдання виконує додаток.
Цей розділ завжди буде показано на самому початку сторінки довідки.
        </summary>

        <usage>
У розділі usage можуть міститися трохи практичніші відомості. Втім, тут не обов’язково
пояснювати докладно усі параметри (це слід залишити для розділу «settings»).

Щоб розпочати новий абзац, вставте порожній рядок, як у нашому прикладі.
Цей рядок, навпаки, розташовуватиметься у тому самому абзаці.

В усіх розділах ви можете використовувати простий код HTML, зокрема для <b>жирного</b> або
<i>курсивного</i> тексту. Втім, не слід зловживати таким форматуванням.

Розділ usage завжди є другим розділом, який буде показано на сторінці довідки.
        </usage>

        <section id="sectionid" title="Типовий розділ" short_title="Типовий">
Якщо потрібно, ви можете додавати розділи між розділом usage та settings.
Втім, зазвичай, у вас не повинно виникнути потреби у таких розділах під час документування додатків. Атрибут «id»
дає точку прив’язки для переходу до цього розділу з меню навігації. Атрибут «short_title»
визначає скорочений заголовок для панелі навігації. Цей атрибут є необов’язковим, типово,
буде використано основний «title» для заголовка розділу і для посилання на панелі
навігації.

У будь-якому розділі ви можете вставити посилання на подальшу інформацію. Для цього вставте такий код:

<link href="URL">назва посилання</link>

Де URL може бути зовнішнім посиланням, наприклад http://rkward.kde.org .
На сторінках довідки передбачено декілька спеціалізованих варіантів адрес:

<link href="rkward://page/шлях/ід_сторінки"/>

Такі адреси надають змогу посилатися на сторінки довідки з rkward (не сторінки додатків).

<link href="rkward://компонент/[простір_назв/]ід_компонента"/>

Так можна посилатися на сторінки довідки іншого додатка. Частину [простір_назв/] можна пропустити
(у цьому випадку використовуватиметься стандартний простір назв rkward, приклад:
<link href="rkward://component/import_spss"/> і
<link href="rkward://component/rkward/import_spss"/> є еквівалентними).
Ідентифікатор ід_компонента є тим самим, який було визначено у .pluginmap.

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

Посилання на довідку з R щодо «rfunction».

Зауважте, що назви посилань для цього типу посилань буде створено автоматично.
        </section>

        <settings>
                <caption id="ід_вкладки_або_фрейма"/>
                <setting id="ід_елемента">
Опис графічного елемента, що ідентифікується вказаним ідентифікатором
                </setting>
                <setting id="ід_елементаb" title="опис">
Зазвичай, заголовок (title) елемента графічного інтерфейсу буде видобуто з
визначення XML додатка автоматично. Втім,
для деяких елементів графічного інтерфейсу цього опису може бути недостатньо для надійної ідентифікації.
У цьому випадку ви можете додати заголовок явним чином за допомогою атрибута «title».
                </setting>
                <setting id="ід_елементаc">
Опис графічного елемента, який позначено ідентифікатором «ід_елементаc»
                </setting>
                [...]
        </settings>

        <related>
Типово, розділ related просто містить посилання, ось так:

<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>
У розділі technical (необов’язковий, завжди останній) можуть міститися деякі подробиці
щодо реалізації додатка, які можуть бути корисними лише розробникам RKWard. Цей розділ
корисний для додатків, які було розроблено для вбудовування у багато інших додатків.
Тут можуть бути подробиці щодо параметрів, доступних для налаштовування вбудованого додатка,
і того, які розділи коду містять відповідний код R.
        </technical>
</document>