Компиляция книги помощи
После того как все исходные файлы и файл определения книги помощи подготовлены,
можно приступать к её генерации. Она состоит из двух процедур, выполняемых,
как правило, итеративно.
- Запуск компилятора.
Выполняется с помощью функции compile-book.
- Сохранение якорей.
По мере завершения книги помощи, все встречающиеся в ней якоря,
должны быть помещены в отдельный файл
для эффективной работы функции помощи во времени исполнения программы.
Компилятор собирает книгу в
целевой папке следующим образом:
- создаёт соответствующую структуру подпапок,
- копирует без изменения вспомогательные папки и
файлы, например, графические,
- транслирует исходные статьи с возможным разбиением на страницы сегментов,
- генерирует навигационные страницы
предметного указателя и
подробного оглавления.
- {(anchor-a "DEFINE-BOOK" :suffix t)}
- {(anchor-a "COMPILE-BOOK" :suffix t)}
- Формат файла якорей
- {(anchor-a "DUMP-ANCHORS" :suffix t)}
- {(anchor-a "ENSURE-BOOK" :suffix t)}
- {(anchor-a "index-compiler")}
- {(anchor-a "toc-compiler")}
[функция]
compile-book
Сигнатура
compile-book name-or-system &rest args =>
Пакет
ystok.help
Аргументы
- name-or-system
- Разрабатываемая книга помощи — экземпляр класса book-system —
или имя книги.
- args
- Прочие ключевые аргументы для стандартной операции
ASDLite
:compile
.
Возвращаемые значения
Нет.
Описание
Функция запускает компилятор книги, обращаясь к стандартной функции
ASDLite:
(apply #'asd:operate :compile 'name-or-system args
Формат файла якорей
Файл якорей реализует в компактном виде
отображение между именами якорей и файлами страниц
готовой книги помощи.
Этот файл как бы "выставляет якоря напоказ", что необходимо для обслуживания
запроса помощи из
прикладной программы.
Прикладная программа может либо загрузить файл якорей сразу после запуска,
либо отложить её до момента первого обращения к книге.
Файл якорей имеет следующий формат
;;; Help Book Anchors ; начальный комментарий
(:ID "yhelp" ; идентификатор книги
:START "introduction.html" ; начальная страница
:DESCRIPTION "Book title") ; полное название книги
{(anchor . uri-string) | (anchor {uri-desc}+)}+
:TEXT
{(anchor (namestring start . end)+)}+
Здесь
- uri-string
- Строка URI относительно целевой папки книги.
- uri-desc
- uri-string
или (uri-string . segment-title)
- segment-title
- Значение свойства
title
статьи или сегмента.
- namestring
- Строка спецификации компилированного бинарного файла контекстных подсказок.
- start, end
- Начальная и конечная позиция в бинарном файле namestring
текста контекстной подсказки, соответствующей anchor.
[обобщённая функция]
dump-anchors
Сигнатура
dump-anchors book-name-or-system &optional pathname => pathname
Пакет
ystok.help
Аргументы
- book-name-or-system
- Разрабатываемая книга помощи — экземпляр класса book-system —
или имя книги.
- pathname
- Спецификация целевого файла якорей, в который компилируются все якоря книги.
Умолчанием служит файл book_id.anc в целевой папке книги.
Возвращаемые значения
Спецификация созданного файла якорей.