Компоненты книги помощи
Классы компонентов книги являются подклассами компонентов,
определённых в ASDlite —
компактном варианте библиотеки ASDF.

На рисунке представлено лишь дерево основных классов. Вспомогательные
подклассы, например, topic-mixin
, не показаны.
[класс]
book-system
Аннотация
Класс дескрипторов разрабатываемых книг помощи.
Пакет
ystok.help
Надклассы
help-module-mixin, book-mixin, asd:system
Описание
Ключевые аргументы инициализации и подробности описываются в следующей статье:
{(anchor-a "DEFINE-BOOK" :suffix t)}.
[класс]
chapter
Аннотация
Класс, экземпляры которого представляют разделы (главы) или подразделы.
Пакет
ystok.help
Надклассы
help-module-mixin, asd:module
Ключевые аргументы :option value
- name
- Имя раздела: строка или символ; для символа берётся
печатное имя и преобразуется в нижний регистр. В нём не допустимы пробелы,
буквы, кроме латинских, и другие специальные знаки. Разрешены
лишь литеры, соответствующие компоненту path спецификации URI.
- pathname
- Файловый путь к исходной папке,
откуда берутся препарированные автором файлы раздела.
- Стандартный аргумент ASDlite, не оценивается.
Если не задан, то в качестве значения принимается
относительный путь — подпапка name.
Если задан, путь должен указывать на папку (директорий), т.е. обязательным является конечный слэш,
прямой (/) или обратный (\). Путь может быть как абсолютным, так и относительным
— относительно исходной папки непосредственного родительского компонента.
Допустимо указывать логический путь.
- output-pathname
- Файловый путь к целевой папке,
куда компилятор поместит готовые файлы раздела.
- Аргумент не оценивается. Если не
задан, то в качестве значения принимается
относительный путь — подпапка name.
Если задан, путь должен указывать именно на папку (директорий), т.е. обязательным является конечный слэш,
прямой (/) или обратный (\). Путь может быть как абсолютным, так и относительным
— относительно целевой папки непосредственного родительского компонента.
Если есть ".", то файлы раздела будут размещены непосредственно
в родительской папке.
Допустимо указывать логический путь.
- start
- Имя компонента — начальной статьи.
Страница этой статьи (точнее, её нулевого сегмента) называется также
начальной страницей раздела.
Она будет помещена первой в линейном упорядочении всех страниц.
- Аргумент не оценивается. Если не задан, то в качестве значения принимается
первая в списке компонентов статья главы, т.е. типа
topic.
- dump
- Задаёт значение по умолчанию для слота dump статей данного раздела.
Умолчание: :parent
.
Описание
Экземпляры класса chapter
представляют разделы (главы) или подразделы.
Компонентами раздела могут, в свою очередь, быть подразделы, статьи, вспомогательные файлы
и папки. Порядок задания компонентов определяет линейную последовательность
статейных страниц. В эту последовательность вносят вклад все компоненты типа
topic.
[класс]
parsed-file
Аннотация
Класс, экземпляры которого представляют разбираемые файлы,
которые "пропускаются" через компилятор.
Пакет
ystok.help
Надклассы
asd:dynamic-file
Подклассы
context-popup,
parsed-html-file,
text-topic
Описание
Класс parsed-file
представляет препарированные автором
файлы, которые подаются на вход компилятора:
- либо файл в гипертекстовом формате для книги помощи,
- либо текстовый файл регулярной страницы или контекстной подсказки,
показываемой прикладной программой
непосредственно (а не в браузере).
Данный класс "абстрактный" (в терминологии С++) или "примесь"
(mixin в терминологии Лисп), т.е. непосредственно от экземпляры не порождаются,
а порождаются от его подклассов.
Ключевые аргументы :option value
- name
- Имя целевого файла страницы: строка или символ; для символа берётся
печатное имя и преобразуется в нижний регистр.
Тип файла, если "html" желателен, может быть указан внутри
name после точки.
- pathname
- Точное имя, тип, и, возможно, путь к
исходному файлу.
Путь может быть как абсолютным, так и относительным —
относительно исходной папки непосредственного родительского компонента.
- Стандартный аргумент ASDlite, не оценивается.
Если не задан, то в качестве значения принимается name с типом по умолчанию
(тип файла также может быть указан непосредственно в name).
Допустим также логический путь.
- Пример задания логического пути:
:pathname #P"LIB:doc;settings;general.html"
- title
- Строка — альтернативный заголовок статьи, который будет помещен в
оглавление вместе с гиперссылкой на данную статью.
Элемент TITLE
перекрывает значение этого аргумента.
- description
- Строка аннотации (краткого описания), которая будет высвечиваться
в качестве всплывающей подсказки в оглавлении.
Метаэлемент
<МETA name="description" ...>
перекрывает значение этого аргумента.
[класс]
parsed-html-file
Аннотация
Класс, экземпляры которого представляют исходные файлы в формате HTML,
подаваемые на вход компилятора.
Пакет
ystok.help
Надклассы
parsed-file
Подклассы
navigation,
popup,
topic
Ключевые аргументы :option value
- braces
- Булево значение, задающее, допустимы ли шаблонные выражения
в фигурных скобках внутри тела исходной статьи.
Описание
Класс parsed-html-file
представляет препарированные автором
файлы в гипертекстовом формате, которые "пропускаются" через компилятор.
Тип исходных и результирующих файлов
по умолчанию есть "html".
Как и parsed-file, данный класс
"абстрактный", т.е. непосредственно от экземпляры не порождаются.
[класс]
topic-mixin
Аннотация
Класс, экземпляры которого представляют регулярные статьи, формирующие
последовательность страниц книги и отображаемые в правой фрамуге.
Пакет
ystok.help
Подклассы
text-topic,
topic
Описание
Класс parsed-file
регулярные страницы, формируеющие
последовательность страниц книги.
Данный класс "абстрактный" (в терминологии С++) или "примесь"
(mixin в терминологии Лисп), т.е. непосредственно от экземпляры не порождаются,
а порождаются от его подклассов.
[класс]
topic
Аннотация
Класс, экземпляры которого представляют регулярные статьи, порожденные
из исходных HTML-файлов.
Пакет
ystok.help
Надклассы
topic-mixin,
parsed-html-file
Ключевые аргументы :option value
- index
- Если есть
nil
или :none
,
то при компиляции предметного указателя
данная статья будет исключена из рассмотрения.
- Аргумент не оценивается. Если не задан,
то подавить индексацию статьи можно, указав
meta="ROBOTS" content="NOINDEX"
в самой исходном файле.
- dump
- Указание того, следует ли помещать в файл якорей
определённые в данной статье якоря.
Умолчание: :parent
.
Описание
Аргумент dump может принимать одно из следующих значений:
nil
- При создании файла якорей следует исключить
данную статью из рассмотрения, поскольку она напрямую из
прикладной программы
не открывается и нет необходимости выставлять якоря напоказ.
t
- Якоря из данной статьи будут сохранены в файле якорей.
:parent
- Либо взять значение из слота dump
объемлющего раздела,
либо, для статьи верхнего уровня, из слота
dump книги.
[класс]
text-topic
Аннотация
Класс, экземпляры которого представляют регулярные статьи, порожденные
из исходных текстовых файлов.
Пакет
ystok.help
Надклассы
topic-mixin,
parsed-file
Ключевые аргументы :option value
- toc-level
- Целое число, большее, 1 или
nil
.
- use-templates
- Одно из значений:
nil
, t
или :braces
.
Умолчание: значение аргумента
:use-templates,
заданное в определении книги.
Описание
Аргумент toc-level задаёт уровень данной статьи в оглавлении книги.
По умолчанию статья помещается в соответствии с
уровнем сегмента
(Cам текст заголовка может быть указан при помощи аргумента.
:title.)
Если toc-level есть nil
, то при
компиляции оглавления
данная статья будет исключена из рассмотрения.
Аргумент use-templates может принимать одно из следующих значений.
nil
- Исходный файл статьи является "плоским" текстовым файлом,
который попросту копируется в целевую папку книги или раздела;
t
- Исходный файл статьи является шаблоном,
т.е. может содержать псевтотеги;
к содержимому файлов будет применена функция
html-template:fill-and-print-template
.
Шаблонные выражения в фигурных скобках не допускаются.
:braces
- Исходные файл является шаблоном и в нём допустимы шаблонные выражения
в фигурных скобках вида
{выражение}
.
Если в определении книги использование
шаблонов вовсе запрещено, т.е. указано
:use-templates nil
,
то в текстовых статьях разметка шаблонов также игнорируется независимо
от значения use-templates.
Технология шаблонов YHTML-Template
применима не только к HTML-файлам, но и к произвольным текстовым файлам.
Разумеется, якоря из таких файлах
не извлекаются.
[класс]
navigation-mixin
Аннотация
Абстрактный класс, экземпляры которого представляет страницы,
служащие для навигации по книге, не для отображения
"предметного содержимого".
Пакет
ystok.help
Надклассы
нет
Ключевые аргументы :option value
- tab
- Строка, задающая надпись на ярлычке.
Описание
Каждая навигационная страница верхнего уровня отображается в левой
фрамуге в собственной "вкладке" c ярлычком, например,
Указатель или Оглавление.
[класс]
navigation
Аннотация
Класс, экземпляры которого представляет страницы для навигации по книге.
Каждая такая страница основана на исходном HTML-файле, который не может быть разбит на сегменты.
Навигационные страницы верхнего уровня отображаются левой фрамуге.
Пакет
ystok.help
Надклассы
navigation-mixin,
parsed-html-file
[класс]
frameset
Аннотация
Класс для генерации набора фрамуг.
Пакет
ystok.help
Надклассы
generated-component
Ключевые аргументы :option value
- name
- Имя целевого файла набора фрамуг, должно быть
"help.html"
.
Описание
Экземпляр данного класса представляет набор фрамуг —
вспомогательный файл, генерируемый автоматически.
Компонент данного типа должен быть единственным в и располагаться
на верхнем уровне определения книги.
Если текст заголовка окна (аргумент title
) не задан,
он берётся из определения книги.
Другая возможность — препарировать файл help.html
вручную и поместить его в определение книги в качестве вспомогательного файла
типа aux-file.
[класс]
aux-file
Аннотация
Класс для представления неразборных вспомогательных файлов.
Пакет
ystok.help
Надклассы
asd:dynamic-file
Ключевые аргументы :option value
- name
- Имя целевого файла страницы: строка или символ; для символа берётся
печатное имя и преобразуется в нижний регистр.
Тип файла, если "html" желателен, может быть указан внутри
name после точки.
- pathname
- Точное имя, тип, и, возможно, путь к
исходному файлу.
Путь может быть как абсолютным, так и относительным —
относительно исходной папки непосредственного родительского компонента.
Допустим также логический путь.
- Стандартный аргумент ASDlite, не оценивается. Если не
задан, то в качестве значения принимается name с типом по умолчанию
(тип файла также может быть указан непосредственно в name).
Описание
Каждый экземпляр данного ласса представляет вспомогательный файл,
который не разбирается компилятором, а попросту копируется в
целевую папку
без попытки анализа его содержимого.
[класс]
aux-folder
Аннотация
Класс для представления неразборных вспомогательных папок.
Пакет
ystok.help
Надклассы
asd:module
Ключевые аргументы :option value
- output-pathname
- Путь к целевой папке,
которая будет полной или частичной копией
исходной.
- Аргумент не оценивается. Если не
задан, то в качестве значения принимается
относительный путь — подпапка name.
Если задан, путь должен указывать на папку (директорий), но конечный слэш,
прямой (/) или обратный (\), необязателен.
Путь может быть как абсолютным, так и относительным
— относительно целевой папки непосредственного родительского компонента.
Если есть "." то файлы из вспомогательной папки будут размещены
непосредственно в родительской папке.
- exclude
- Список файлов, которые не будут копироваться.
Элемент списка задаётся в виде строки или спецификации пути
#P"..."
,
и может содержать шаблонный знак *
.
Сопоставление осуществляется вызовом функции Лисп
pathname-match-p
.
Описание
Класс, экземпляр которого представляет вспомогательную папку.
Такая папка обычно содержит графические файлы и копируется компилятором в
целевую папку
целиком без попытки их анализа.
- {(anchor-a "_EXCLUDE-SUBDIRECTORIES_" :suffix t)}
Аннотация
Класс для наполнения окна контекстной помощи.
Пакет
ystok.help
Надклассы
parsed-file
Описание
Каждый экземпляр данного класса обеспечивает наполнение всплывающего
окна контекстной помощи.
Исходный файл контекстных подсказок является текстовым файлом
с разделителями простейшего вида, которые также служат якорями.
- {(anchor-a "context-help" :class "chapter")}