Компоненты книги помощи

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

Топология классов компонентов YstokHelp

На рисунке представлено лишь дерево основных классов. Вспомогательные подклассы, например, 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-файлам, но и к произвольным текстовым файлам. Разумеется, якоря из таких файлах не извлекаются.

Аннотация

Абстрактный класс, экземпляры которого представляет страницы, служащие для навигации по книге, не для отображения "предметного содержимого".

Пакет

ystok.help

Надклассы

нет

Ключевые аргументы :option value
Строка, задающая надпись на ярлычке.
Описание

Каждая навигационная страница верхнего уровня отображается в левой фрамуге в собственной "вкладке" c ярлычком, например, Указатель или Оглавление.

Аннотация

Класс, экземпляры которого представляет страницы для навигации по книге. Каждая такая страница основана на исходном 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.
Описание

Класс, экземпляр которого представляет вспомогательную папку. Такая папка обычно содержит графические файлы и копируется компилятором в целевую папку целиком без попытки их анализа.

[класс] context-popup

Аннотация

Класс для наполнения окна контекстной помощи.

Пакет

ystok.help

Надклассы

parsed-file

Описание

Каждый экземпляр данного класса обеспечивает наполнение всплывающего окна контекстной помощи. Исходный файл контекстных подсказок является текстовым файлом с разделителями простейшего вида, которые также служат якорями.