YstokHelp API

YstokHelp API представляет собой набор примитивов языка Коммон Лисп, которые программист может использовать в своей программе для того, что вызвать книгу помощи и открыть её на определенной странице. Эти примитивы определены в пакете ystok.help.

[пакет] ystok.help

Кличка

help

Описание

Пакет символов, содержащий все необходимые константы, переменные, макросы и функции системы YstokHelp. Экспортированы (exported), в основном, примитивы, необходимые во время исполнения прикладной программы.

Символы, реализующие функционал компилятора книги, являются внутренними (internal). Однако при считывании и определения книги, и всех разбираемых файлов данный пакет делается текущим, т.е. с ним связывается переменная *package*.

[класс] book

Аннотация

Класс дескрипторов готовых книг помощи.

Пакет

ystok.help

Надклассы

book-mixin

Ключевые аргументы инициализации
:title
Название книги, фигурирующее в меню Помощь
Обычно то же, что и у разрабатываемой книги помощи.
:location
Спецификация папки готовой книги помощи на компьютере пользователя. Может быть задан как в виде абсолютного файлового пути, так и относительного — в последнем случае он сливается со значением переменной *default-book-pathname*.
:external-format
Внешний формат файлов книги — спецификация кодировки букв и кодировки перехода на новую строку. Если не указан, вычисляется исходя из компьютерной платформы и установок операционной системы.
Описание

Экземпляр класса book является дескриптором готовой книги помощи. Во время исполнения прикладной программы он помогает переадресовать поступающие от пользователя запросы помощи к нужным страницам книги.

Дескриптор создаётся ещё при сборке прикладной программы, а во время её исполнения переводится в полностью рабочее состояние в результате загрузкой компилированного файла якорей.

[переменная] *default-book*

Пакет

ystok.help

Начальное значение

nil

Описание

Хранит дескриптор готовой книги помощи по умолчанию, который используется исполняемой программой для выполнения запросов о помощи. Во время разработки книги допустимо в эту переменную помещать также дескриптор класса book-system (совместимость для облегчения отладки).

[переменная] *default-book-pathname*

Пакет

ystok.help

Начальное значение

nil

Описание

Значением глобальной переменной должна быть спецификация папки на компьютере пользователя, где по умолчанию хранятся готовые книги помощи. Из этой папки происходит "дозагрузка" якорей в дескриптор готовой книги помощи.

[функция] register-book

Сигнатура

register-book book-or-id &rest args => book

Пакет

ystok.help

Аргументы
book-or-id
Строка-идентификатор книги или дескриптор книги помощи.
args
Список ключевых аргументов, передаваемый в функцию make-instance.
Возвращаемое значение

Переданный в качестве первого аргумента дескриптор или новый дескриптор готовой книги помощи, экземпляр класса book.

Описание

Функция предназначена для создания дескриптора "полуготовой" книги в момент компиляции прикладной программы и регистрации её во внутреннем реестре. Это достигается передачей в качестве аргумента book-or-id строки-идентификатора книги. Таблица якорей остается пустой и загружается лишь во время исполнения программы путем вызова функций load-book или ensure-book.

[функция] load-book

Сигнатура

load-book pathname &optional book => book

Пакет

ystok.help

Аргументы
pathname
Спецификация скомпилированного файла якорей.
book
Дескиптор готовой книги помощи, экземпляр класса book, в котором может отсутствовать таблица якорей.
Возвращаемые значения

Дескриптор готовой книги помощи, переданный в качестве аргумент book, или автоматически созданный, если аргумент book не задан.

Описание

Функция загружает файл якорей в дескриптор готовой книги помощи, переводит таблицу якорей во внутреннее представление для эффективного выполнения функций помощи.. Если аргумент book не задан, то создаётся новый дескриптор. В последнем случае, идентификатор и другие свойства книги извлекаются из указанного файла.

[обобщённая функция] ensure-book

Сигнатура

ensure-book book-or-id => book-mixin

Пакет

ystok.help

Аргументы
book-or-id
Идентификатор книги помощи или экземпляр одного из двух подклассов класса book-mixin:
Возвращаемое значение

Совпадает со значением аргумента book-mixin.

Описание

Для готовой книги помощи функция проверяет, загружен ли файл якорей, и, если нет, вызывает load-book, чтобы загрузить его.

Для разрабатываемой книги помощи функция ничего не делает. Возможность передавать в неё экземпляр book-system добавлена для совместимости и облегчения проверки работоспособности на этапе разработки и увязки программы с системой помощи.

[функция] view-topic

Сигнатура

view-topic locator &key book interface displayer =>

Пакет

ystok.help

Аргументы
locator
Локатор или список локаторов, служащий для внутренней идентификации статьи.
book
Идентификатор или дескриптор книги помощи по умолчанию.
interface
nil или объект-окно верхнего уровня, через которое пользователь запросил о помощи.
displayer
nil или элемент интерфейса, для которого запрашивается помощь.
Возвращаемые значения

Нет.

Описание

Локатор — объект типа ystok.uri:uri или строка одного из следующих видов:
"anchor" | "#anchor"| "//book_id#anchor" | "//book_id/" | "/path" | "//book_id/path" | "/path#anchor" | "//book_id/path#anchor".
Эта строка аналогична гибкой ссылке, используемой в исходных HTML-файлах разрабатываемой книги помощи, с той лишь разницей, что при отсутствии каких-либо разделителей строка трактуется как anchor, а не как path (как это принято в спецификации URI).

Функция открывает книгу помощи на странице, содержащей указанный якорь anchor и/или находящейся в пути path. Когда в локаторе задан и якорь, и путь, путь обычно задаёт только физическую папку (без указания файла), где ищется страница с определением якоря.

Если аргумент book не задан, по умолчанию якорь ищется в книге *default-book*. Если существуют несколько страниц, содержащих данный якорь, то высвечивает запрос, на какой именно следует перейти. Если ни одной страницы не найдено, то выдается предупреждение в виде диалога.

В качестве аргумента book может передаваться экземпляр как класса book, так book-system. Последняя возможность удобна для отладки функций помощи на этапе разработки.

Не все браузеры позволяют прокручивать открываемую страницу, так чтобы показать указанный фрагмент. Тогда страница будет показана с начала.

Переход на фрагмент внутри страницы статьи верхнего уровня по умолчанию не реализован. Обычно такой статьёй служит обзор "O книге помощи". Маловероятно, что из прикладной программы потребуются переходы внутрь него — его достаточно показать с самого начала.

Когда локатор представлен строкой URI, функция разбирает её. Чтобы корректно преобразовать фрагмент, необходимо передать аргумент :fragment-char-p функции uri:parse-uri, а значит, знать язык. Обычно само приложение подразумевается скомпилированным под определённый язык. Поэтому функция ещё при компиляции проверяет системные возможности (features), вроде :Russian, вместо того, чтобы пытаться извлечь язык из какой-нибудь книги во время исполнения.

[функция] view-page

Сигнатура

view-page &key uri book interface =>

Пакет

ystok.help

Аргументы
book
Идентификатор книги или объект — готовая книга помощи (если доподлинно известен). Может передаваться экземпляр как класса book, так book-system (удобно на стадии разработки).
uri
Спецификация URI в виде строки или экземпляра uri:uri.
interface
nil или объект-окно верхнего уровня, через которое пользователь запросил о помощи.
Возвращаемые значения

Нет.

Описание

Открыть книгу помощи на странице, заданной точным адресом uri. Если аргумент book не задан, по умолчанию страница ищется в книге *default-book*. Если аргумент uri есть nil, то функция открывает начальную страницу книги помощи.

Функция view-page требует точного указания файла страницы, в то время как view-topic позволяет указать лишь якорь. Чаще второй вариант предпочтительней, ибо не требует от автора книги знать точное местоположения файла, где будет храниться та или иная статья.