Список ссылок применяется на разных страницах. Например, на начальной странице раздела уместно небольшое перечисление всех подразделов.
Компилятор поддерживает несколько функций и шаблоные переменные для генерации списков ссылок.
Шаблонная переменная выглядит аналогично переменной во многих языках программирования. В момент генерации каждая переменная связывается, т.е. получает значение
nil
(равносильно булевому значению 'ложь').Ниже перечислены переменные, связываемые при генерации всех видов списков.
item-uri
href
;
определяется сегментом, где расположен якорь.item-content
item-class
item-title
title
,
либо задаётся самым первым элементом Hi
;
заголовок представляет собой строку текста (в следующих версиях будет браться содержимое элемента с форматированием),
который послужит содержимым элемента A
.item-description
description
сегмента, в который ведёт ссылка; этот текст попадает в атрибут title
.item
Связывание шаблонных переменных на каждой итерации цикла по (под)заголовкам.
[функция] toc-children &key heading-class depth referrer suffix
H
i
с помощью атрибута class="css-class"
.
Умолчание есть :all
.t
.Список ассоциативных списков, связывающих шаблонные переменные, для всех подзаголовков, вложенных в компонент referrer. Список отсортирован в "естественном" порядке вхождения статей в книгу.
В качестве referrer можно указать одну из специальных переменных:
*current-chapter*
*current-topic*
По умолчанию, если текущая статья является начальной в разделе,
в качестве компонента принимается *current-chapter*
,
иначе *current-topic*
.
Собираются все подзаголовки, разница уровней которых с уровнем заголовка
самого component не превышает depth.
Образец heading-class сопоставляется со значением атрибута class
элементов H
i
.
Он задается в синтаксисе языка Лисп согласно следующему правилу:
pattern ::= nil | keyword | string | (not pattern) | (and pattern...) | (or pattern...)
Причем
"*"
и :all
сопоставляются с любым значением атрибута class="css-class"
, в том числе, пустым;nil
и :none
сопоставляются с пустым значением атрибута, т.е. когда он не задан или есть
пустая строка "";
"css-class"
может содержать несколько имён классов, разделённых пробелами.Если вложенные подзаголовки отсутствуют внутри component,
возвращается пустой список ()
, т.е. nil
.
Если значение suffix истино, значение
шаблонной переменной
item-content
будет включать и текст заголовка, и дополнительные свойства, нампример,
category.
Если значение suffix есть nil
,
вслед за содержимым ничего не выдаётся.
На начальной странице раздела верхнего уровня часто размещают его краткое оглавление. Для этого в исходный код страницы нужно поместить шаблон следующего вида:
<ul> <!-- TMPL_LOOP (toc-children) --> <li><a href="{item-uri}" class="{item-class}" title="{item-description}">{item-content}</a></li> <!-- /TMPL_LOOP --> </ul>
Связывание шаблонных переменных на каждой итерации цикла по именам якорей.
[функция] anchor-topics &rest anchors
[функция] atopics &rest anchors
Список ассоциативных списков, связывающих шаблонные переменные, для всех из указанных якорей, найденных в книге. Список отсортирован в "естественном" порядке вхождения статей в книгу.
Шаблон списка ссылок позволяет указать имена якорей и не требует спецификации файлов, где эти якоря находятся.
Если ни один из якорей не найден в книге, возвращается пустой список
()
, т.е. nil
, а в журнал ничего не пишется.
Типичным применением является пункт См.также, замыкающий и данную статью. Он создан с помощью следующего шаблона.
<ul> <!-- TMPL_LOOP (anchor-topics "help-scheme" "index-compiler") --> <li><a href="{item-uri}" class="{item-class}" title="{item-description}">{item-content}</a></li> <!-- /TMPL_LOOP --> </ul>
Функция может вызываться в шаблоне из псевдо-элемента условной компиляции для проверки, нужно ли вставлять определённый код в результирующую страницу. Например:
<!-- TMPL_IF (anchor-topics "SLAVE-INTERFACE") --> <tr>HTML-код, вставляемый, только если якорь определён где-либо...</tr> <!-- /TMPL_IF -->
item-a item &key class suffix
item
внутри списка ссылок.A
.t
.Функция предназначена для использования внутри шаблонных циклов
на основе toc-children
и anchor-topics.
Она возвращает HTML-код с элементом A
и атрибутами,
составленный на основе значений других
шаблонных переменных.
Если в качестве class явно передаётся nil
,
то атрибут class
не выдаётся.
Если class не задан, то по умолчанию в качестве значения атрибута
class
будут перечислены те классы, которые
Если значение suffix истино, к содержимому
заголовочного элемента
присоединяются дополнительные свойства, нампример,
category.
Если значение suffix есть nil
,
вслед за содержимом ничего не выдаётся.
Следующие два фрагмента почти эквивалентны.
<ul> <!-- TMPL_LOOP (anchor-topics "help-scheme" "index-compiler") --> <li><a href="{item-uri}" class="{item-class}" title="{item-description}">{item-content}</a></li> <!-- /TMPL_LOOP --> </ul>
<ul> <!-- TMPL_LOOP (anchor-topics "help-scheme" "index-compiler") --> <li>{(item-a item)}</li> <!-- /TMPL_LOOP --> </ul>