YstokHelp API представляет собой набор примитивов языка Коммон Лисп, которые программист может использовать в своей программе для того, что вызвать книгу помощи и открыть её на определенной странице. Эти примитивы определены в пакете ystok.help.
help
Пакет символов, содержащий все необходимые константы, переменные, макросы и функции системы YstokHelp. Экспортированы (exported), в основном, примитивы, необходимые во время исполнения прикладной программы.
Символы, реализующие функционал компилятора книги, являются внутренними (internal).
Однако при считывании и определения книги, и всех разбираемых файлов
данный пакет делается текущим, т.е. с ним связывается переменная
*package*
.
Класс дескрипторов готовых книг помощи.
book-mixin
Экземпляр класса book
является
дескриптором готовой книги помощи.
Во время исполнения прикладной программы он помогает переадресовать
поступающие от пользователя запросы помощи к нужным страницам книги.
Дескриптор создаётся ещё при сборке прикладной программы, а во время её исполнения переводится в полностью рабочее состояние в результате загрузкой компилированного файла якорей.
nil
Хранит дескриптор готовой книги помощи по умолчанию, который используется исполняемой программой для выполнения запросов о помощи. Во время разработки книги допустимо в эту переменную помещать также дескриптор класса book-system (совместимость для облегчения отладки).
nil
Значением глобальной переменной должна быть спецификация папки на компьютере пользователя, где по умолчанию хранятся готовые книги помощи. Из этой папки происходит "дозагрузка" якорей в дескриптор готовой книги помощи.
register-book book-or-id &rest args => book
make-instance
. Переданный в качестве первого аргумента дескриптор или новый дескриптор готовой книги помощи, экземпляр класса book.
Функция предназначена для создания дескриптора "полуготовой" книги в момент компиляции прикладной программы и регистрации её во внутреннем реестре. Это достигается передачей в качестве аргумента book-or-id строки-идентификатора книги. Таблица якорей остается пустой и загружается лишь во время исполнения программы путем вызова функций load-book или ensure-book.
load-book pathname &optional book => book
Дескриптор готовой книги помощи, переданный в качестве аргумент book, или автоматически созданный, если аргумент book не задан.
Функция загружает файл якорей в дескриптор готовой книги помощи, переводит таблицу якорей во внутреннее представление для эффективного выполнения функций помощи.. Если аргумент book не задан, то создаётся новый дескриптор. В последнем случае, идентификатор и другие свойства книги извлекаются из указанного файла.
ensure-book book-or-id => book-mixin
book-mixin
:
Совпадает со значением аргумента book-mixin.
Для готовой книги помощи функция проверяет, загружен ли файл якорей, и, если нет, вызывает load-book, чтобы загрузить его.
Для разрабатываемой книги помощи функция ничего не делает. Возможность передавать в неё экземпляр book-system добавлена для совместимости и облегчения проверки работоспособности на этапе разработки и увязки программы с системой помощи.
view-topic locator &key book interface displayer =>
nil
или объект-окно верхнего уровня, через которое пользователь запросил о помощи.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 &key uri book interface =>
book
,
так book-system
(удобно на стадии разработки).uri:uri
.
#
fragment.nil
или объект-окно верхнего уровня, через которое пользователь запросил о помощи.Нет.
Открыть книгу помощи на странице, заданной точным адресом uri.
Если аргумент book не задан, по умолчанию страница ищется в книге
*default-book*.
Если аргумент uri есть nil
, то функция открывает начальную страницу
книги помощи.
Функция view-page
требует точного указания файла страницы,
в то время как view-topic
позволяет указать лишь якорь. Чаще второй
вариант предпочтительней, ибо не требует от автора книги знать точное местоположения
файла, где будет храниться та или иная статья.