Оглавление перечисляет все разделы, подразделы, статьи и подстатьи всех уровней, не превышающих изначально заданный в определении книги помощи.
Чтобы задать компиляцию оглавления, следует поместить в определение книги компонент типа toc.
Класс, экземпляр которого представляет автоматически создаваемое подробное оглавление книги.
navigation-mixin, generated-component
"Оглавление"
.:title
означает, что оглавление собирается из
заголовков статей или сегментов;(:h1 [:h2 [:h3]] [(tags-with-explict-toc-level-only)])
— список ключей
заголовочных элементов (headings);help="toc-level:
n".В определении книги помощи
допустим единственный компонент типа toc
— на самом верхнем уровне.
Имя компонента-оглавления задаёт имя файла, который будет помещён в корень целевой папки книги.
create-toc book-name-or-system &key source max-level pathname =>
toc
.toc
.Нет.
Функция запускает компилятор, который собирает заголовки из всех исходных файлов статей помещает их в целевой файл. Заголовок включается в оглавление, если
toc-level:n
,
где n не есть none
или nil
.Как именно определяются заголовки, зависит от режима:
Вызов функции create-toc
происходит автоматически при
выполнении операции :compile
ASDlite
и комплиляции всей книги.
:title
В этом режиме источником заголовков служат
TITLE
,
заданные внутри HEAD
исходных файлов статей,:title
.Окончательный уровень заголовка сегмента определяется следующим образом (статья без разделителей тождественна своему нулевому сегменту).
Сегмент | Окончательный уровень |
---|---|
раздел (глава) | 1 |
подраздел | уровень родителя +1 |
нулевой сегмент статьи на уровне книги | 1 |
ненулевой сегмент статьи на уровне книги | 2 |
нулевой сегмент начальной статьи (под)раздела | уровень (под)раздела |
ненулевой сегмент начальной статьи или произвольный сегмент неначальной статьи (под)раздела | уровень (под)раздела +1 |
Список ключей heading-list имеет вид:
(:h1 [:h2 [:h3]] [tags-with-explict-toc-level-only])
,
где последним элементом tags-with-explict-toc-level-only может
быть указан подсписок ключей тегов.
Для примера обсудим список ключей (:h1 :h2 (:h3))
.
<h1>
text</h1>
и <h2>
text</h2>
поставляют заголовки при условии, что их окончательный уровень
попадает в требуемый диапазон и для них не указан атрибутhelp="toc-level:none"
.<h3>
text</h3>
поставляют заголовки при условии,
что их окончательный уровень попадает в требуемый диапазон.<h3 help="toc-level:
n">
text</h3>
,
т.е. с явным указанием свойства toc-level
атрибута help
,
поставляют заголовки безотносительно их окончательного уровня.h3, h4, h5, h6
заголовки не поставляют.Окончательный уровень заголовка вычисляется следующим образом.
Вид элемента | Окончательный уровень | Примечание |
---|---|---|
<h i help="toc-level: n"> |
n | целое без знака |
<h i> |
уровень_сегмента -1+i | свойство toc-level отсутствует |
<h i help="toc-level: +n"> |
уровень_сегмента -1+i+n | целое со знаком "плюс" |
<h i 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"> |
явное включение, появится в оглавлении на уровне сегмента. |