Компилятор оглавления книги

Оглавление перечисляет все разделы, подразделы, статьи и подстатьи всех уровней, не превышающих изначально заданный в определении книги помощи.

Чтобы задать компиляцию оглавления, следует поместить в определение книги компонент типа toc.

[класс] toc

Аннотация

Класс, экземпляр которого представляет автоматически создаваемое подробное оглавление книги.

Пакет

ystok.help

Надклассы

navigation-mixin, generated-component

Ключевые аргументы :option value
tab
Строка, задающая надпись на ярлычке, например, "Оглавление".
source
Задает, какие элементы HTML формируют оглавление: Умолчание задаётся параметром *default-toc-source*.
max-level
Максимальное число уровней заголовков, собираемых в оглавление книги. В оглавление попадают только заголовки с окончательным уровнем в диапазоне [1...max-level].
Умолчание задаётся параметром *default-toc-max-level*
Описание

В определении книги помощи допустим единственный компонент типа toc — на самом верхнем уровне.

Имя компонента-оглавления задаёт имя файла, который будет помещён в корень целевой папки книги.

[обобщённая функция] create-toc

Сигнатура

create-toc book-name-or-system &key source max-level pathname =>

Пакет

ystok.help

Аргументы
book-name-or-system
Разрабатываемая книга помощи — экземпляр класса book-system — или имя книги.
source, max-level
См. описание аргументов инициализации класса toc.
pathname
Спецификация выходного файла оглавления. Умолчание определяется именем компонента типа toc.
Возвращаемые значения

Нет.

Описание

Функция запускает компилятор, который собирает заголовки из всех исходных файлов статей помещает их в целевой файл. Заголовок включается в оглавление, если

Как именно определяются заголовки, зависит от режима:

Вызов функции create-toc происходит автоматически при выполнении операции :compile ASDlite и комплиляции всей книги.

Режим toc-source :title

В этом режиме источником заголовков служат

Окончательный уровень заголовка сегмента определяется следующим образом (статья без разделителей тождественна своему нулевому сегменту).

СегментОкончательный уровень
раздел (глава)1
подразделуровень родителя +1
нулевой сегмент статьи на уровне книги1
ненулевой сегмент статьи на уровне книги2
нулевой сегмент начальной статьи (под)разделауровень (под)раздела
ненулевой сегмент начальной статьи или произвольный сегмент неначальной статьи (под)разделауровень (под)раздела +1

Режим toc-source heading-list

Список ключей heading-list имеет вид:
 (:h1 [:h2 [:h3]] [tags-with-explict-toc-level-only]),
где последним элементом tags-with-explict-toc-level-only может быть указан подсписок ключей тегов.

Для примера обсудим список ключей (:h1 :h2 (:h3)).

Окончательный уровень заголовка вычисляется следующим образом.

Вид элементаОкончательный уровеньПримечание
<hi help="toc-level: n"> n целое без знака
<hi> уровень_сегмента -1+i свойство toc-level отсутствует
<hi help="toc-level: +n"> уровень_сегмента -1+i+n целое со знаком "плюс"
<hi help="toc-level: -n"> уровень_сегмента -1+i-n целое со знаком "минус"

Уровень сегмента определяется следующим образом (статья без разделителей тождественна своему нулевому сегменту).

СегментУровень сегмента
произвольный сегмент статьи на уровне книги1
произвольный сегмент начальной статьи или нулевой сегмент произвольной статьи (под)разделауровень (под)раздела
ненулевой сегмент неначальной статьи главы или раздела уровень (под)раздела +1

Таким образом, если логический уровень статьи или сегмента равен 1, то окончательный уровень выставляется через i, т.е. самим тегом.

Рекомендации

ТегИспользуйте для...
<h1>
  • главной статьи уровня книги,
  • или начальной статьи раздела/подкниги.
<h2>
  • второстепенной статьи уровня книги,
  • или неначальной статьи подраздела,
  • или ненулевого сегмента.
<h2 help="toc-level: -1"> начальной статьи подраздела
<h3 help="toc-level: n">
(совместно с toc-source '(:h1 :h2 (:h3))
подзаголовок внутри произвольной статьи, который нужно отразить как элемент оглавления указанного уровня (абсолютного или относительного).
<h3 help="toc-level: +0"> явное включение, появится в оглавлении на уровне сегмента.