[макрос] define-book

Сигнатура

define-book name {:option value}* => book

Пакет

ystok.help

Аргументы
name
Задает краткое имя или код разрабатываемой книги помощи: строка или символ; для символа берется печатное имя и преобразуется в нижний регистр.
:option value
Ключевые аргументы, которые аналогичны asd:defsystem и по большей части не оцениваются. Отличные от "стандартных" приведены ниже.
Типы компонентов (задаются ключами)
chapter
Имя раздела (главы). Каждый раздел реализуется экземпляром подкласса asd:module и позволяет сгруппировать статьи в отдельной папке. Имя раздела служит умолчанием для имени исходной и целевой папок раздела, но может быть перекрыто явным заданием аргумента pathname, согласно принципам обязательным является . Единственным нестандартным аргументом раздела является start, см. ниже.
В качестве компонентов допускаются все типы. Раздел уровня два или ниже, т.е. вложенный в другой раздел, называется также подразделом.
topic
Имя исходного HTML-файла "нормальной" статьи.
navigation
Имя исходного HTML-файла навигационной страницы, показываемой в левой фрамуге; не подлежит разбиению на сегменты.
popup
Имя исходного HTML-файла всплывающей заметки.
aux-file
Имя вспомогательного файла, просто копируемого в папку назначения.
aux-folder
Имя вспомогательной подпапки, например, содержащей графические файлы и просто копируемой в папку назначения.
index
Имя файла предметного указателя.
toc
Имя файла оглавления.
Ключевые аргументы :option value
id
Идентификатор книги помощи; если не задан, принимается равным строке, полученной из name. Идентификатор упоминается в гибких ссылках и служит для поиска во внутреннем реестре во время компиляции книги или исполнения прикладной программы. В идентификаторе не допустимы пробелы, буквы, кроме латинских, и другие специальные знаки. Разрешены лишь литеры, соответствующие компоненту host спецификации URI.
title
Строка названия книги, которое будет отображаться в заголовке окна браузера и которое печаталось бы на обложке книги или её на самой первой странице.
author
Стандартный для ASDlite аргумент, строка, в которой перечислены авторы книги через запятую.
description
Стандартный для ASDlite аргумент, строка аннотации или расширенное (полное) название книги.
pathname
Определяет исходную папку, откуда берутся препарированные автором файлы статей и прочие компоненты.
Стандартный для ASDlite аргумент, оценивается.
Если не задан, то в качестве исходной принимается папка, где находится сам файл определения книги.
Допустим логический путь.
output-pathname
Определяет целевую папку, куда компилятор поместит готовую книгу. Аргумент обязательно должен быть задан и, аналогично pathname, оценивается. Конечный слэш, прямой (/) или обратный (\), необязателен.
Допустим логический путь.
start
Имя компонента — начальной статьи. Страница этой статьи (точнее, её нулевого сегмента) называется также начальной страницей книги. Она будет помещена первой в линейном упорядочении всех страниц.
content-header, content-footer
Список ключей, задающий кнопки на панелях инструментов, которые будут показаны соответственно вверху или внизу всех статейных страниц, cм. ниже.
Значение по умолчанию: (:prev :up :next :toggle).
external-format
Внешний формат для исходных файлов книги по умолчанию, см. ниже.
language
Код языка всех страниц книги в виде строки или ключа.
Строка автоматически преобразуется в символ-ключ путём перевода всех букв в верхний регистр и включения в пакет keyword.
charset
Кодировка букв на всех страницах книги.
output-html-format
Внешний формат окончательных HTML-файлов книги.
use-templates
Одно из значений: nil, t или :braces.
Умолчание: :braces (фактически зависит от html-template:*accept-braces-markers*).
aliases
Список определений виртуальных якорей.
dump
Задаёт значение по умолчанию для слота dump статей книги.
Умолчание: t (истина).
environment
Список пар вида
(имя-шаблонной-переменной . значение). Задаёт глобальные значения шаблонных переменных, на которые могут ссылаться псевдотеги.
entities
Список пар вида
("имя-псевдолитеры" . "HTML-элемент"). Каждая ссылка на псевдолитеру внутри книги будет заменяться на указанное значение.
Возвращаемое значения

Экземпляр класса book-system, представляющий дескриртор книги помощи, находящей в стадии разработки/компилирования.

Описание

Макрос создает дескриптор разрабатываемой книги и все её компоненты: разделы, статьи, вспомогательные файлы.

Порядок задания компонентов определяет линейную последовательность статейных страниц. В эту последовательность вносят вклад все компоненты типа topic, а компоненты типа navi-topic исключаются. Первой в последовательности будет страница, полученная из самый первого экземпляра topic. Явное указание аргумента start позволяет скорректировать эту естественную последовательность.

Аргументы title и description задают строки, которые попадут в шапку HTML-файла набора фрамуг. Если title не задан, то в качестве заголовка окна по умолчанию принимается имя книги.

В аргументах content-header или content-footer допустимы ключи

:prev :next
Создают кнопки, позволяющие пролистывать книгу в обратном и прямом направлениях по одной странице.
:up
Создаёт кнопки, позволяющие переходить на начальную страницу раздела. Если пользователь находится на начальной странице, то произойдёт переход на начальную страницу надраздела или книги.
:toggle
Создаёт выключатель, позволяющий спрятать или показать левую фрамугу.

Аргумент external-format определяет, какой кодировке
(1) были подготовлены

(2) будут созданы

Аргумент output-html-format определяет кодировку окончательных страниц книги. Если он не указан, его значение вычисляется из charset. Явное указание кодировки и языка книги необходимы для правильной генерации предметного указателя и оглавления.

Аргумент use-templates может принимать одно из следующих значений.

nil
Исходные файлы страниц книги являются "обычными" HTML-файлами.
t
Исходные HTML-файлы являются шаблонами, т.е. могут содержать псевтотеги и к содержимому файлов будет применена функция html:parse-htt. Шаблонные выражения в фигурных скобках не допускаются.
:braces
Исходные HTML-файлы являются шаблонами и в них допустимы шаблонные выражения в фигурных скобках вида
 {выражение}.

Внутри конкретного исходного HTML-файла или его части способ интерпретации фигурных скобок можно уточнить посредством

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

Аргумент aliases является списком подсписков следующего вида:

(alias_name origin_name ...)

где alias_name — виртуальный якорь, определяемый через реально существующие в книге якорь origin_name. (В подсписке допустимо указывать несколько реальных якорей.)

Аргумент entities является ассоциативным списком. Каждая его пара сопоставляет имени псевдолитеры соответствующий HTML-элемент или любой другой HTML-код, указанный в двойных кавычках. Эта строка-значение сначала подлежит синтаксическому разбору, а затем будет подставляться в результирующие страницы вместо ссылки на псевдолитеру. Ссылки имеют вид escape-последовательности &имя; и аналогичны стандартным именованным HTML-литерам.

Пример
:aliases (("book-descriptor" "BOOK-SYSTEM" "BOOK"))

Виртуальный якорь book-descriptor переопределяется через два исходных якоря BOOK-SYSTEM и BOOK. Каждая гибкая ссылка на виртуальный якорь book-descriptor на страницах книги будет заменена всплывающим меню с двумя пунктами, переадресующими на исходные якоря. В нашем случае оно выглядит так.

См. также