Компиляция книги помощи

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

  1. Запуск компилятора.
    Выполняется с помощью функции compile-book.
  2. Сохранение якорей.
    По мере завершения книги помощи, все встречающиеся в ней якоря, должны быть помещены в отдельный файл для эффективной работы функции помощи во времени исполнения программы.

Компилятор собирает книгу в целевой папке следующим образом:

  1. создаёт соответствующую структуру подпапок,
  2. копирует без изменения вспомогательные папки и файлы, например, графические,
  3. транслирует исходные статьи с возможным разбиением на страницы сегментов,
  4. генерирует навигационные страницы предметного указателя и подробного оглавления.

[функция] 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 в целевой папке книги.
Возвращаемые значения

Спецификация созданного файла якорей.