Генерация списков ссылок

Список ссылок применяется на разных страницах. Например, на начальной странице раздела уместно небольшое перечисление всех подразделов.

Компилятор поддерживает несколько функций и шаблоные переменные для генерации списков ссылок.

Шаблонные переменные для генерации списков

Шаблонная переменная выглядит аналогично переменной во многих языках программирования. В момент генерации каждая переменная связывается, т.е. получает значение

Ниже перечислены переменные, связываемые при генерации всех видов списков.

item-uri
Адрес ссылки (спецификация URI), попадающий в атрибут href; определяется сегментом, где расположен якорь.
item-content
LHTML-объект, представлющий содержимое HTML элемента, где определён якорь.
item-class
Строка имён CSS-классов, указанных в атрибуте class HTML элемента, где определён якорь. Строка содержит имена, разделённые пробелами, и включает лишь только те, которые перечислены в списке *anchor-span-css-classes*.
item-title
Заголовок сегмента, который берётся либо из его свойства title, либо задаётся самым первым элементом Hi; заголовок представляет собой строку текста (в следующих версиях будет браться содержимое элемента с форматированием), который послужит содержимым элемента A.
item-description
Краткое описание ссылки, берётся из свойства description сегмента, в который ведёт ссылка; этот текст попадает в атрибут title.
item
Абстрактный объект, например, заголовок или целевой сегмент, который может послужить в качестве аргумента функции {(aa "ITEM-A" :suffix nil)}.

Динамическое оглавление

Назначение

Связывание шаблонных переменных на каждой итерации цикла по (под)заголовкам.

Сигнатура

[функция] toc-children &key heading-class depth referrer suffix

Пакет

ystok.help

Аргументы
heading-class
Образец имени CSS класса, к которому относятся подбираемые заголовки. Имя класса может быть указано в HTML-элементах Hi с помощью атрибута class="css-class". Умолчание есть :all.
depth
Наибольшая глубина вложенности подзаголовков внутри component. Умолчание есть 1.
referrer
Задает компонент книги, по которому строится оглавление.
suffix
Булево значение,
умолчание есть t.
Значение

Список ассоциативных списков, связывающих шаблонные переменные, для всех подзаголовков, вложенных в компонент referrer. Список отсортирован в "естественном" порядке вхождения статей в книгу.

Описание

В качестве referrer можно указать одну из специальных переменных:

*current-chapter*
Означает оглавление раздела, в который непосредственно входит статья.
*current-topic*
Означает оглавление самой текущей статьи, которое будет содержать все подзаголовки по из всех её сегментов.

По умолчанию, если текущая статья является начальной в разделе, в качестве компонента принимается *current-chapter*, иначе *current-topic*. Собираются все подзаголовки, разница уровней которых с уровнем заголовка самого component не превышает depth.

Образец heading-class сопоставляется со значением атрибута class элементов Hi. Он задается в синтаксисе языка Лисп согласно следующему правилу:

pattern ::= nil | keyword | string
      | (not pattern) | (and pattern...) | (or pattern...)

Причем

Если вложенные подзаголовки отсутствуют внутри 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

Пакет

ystok.help

Аргументы
anchors
Список строк или объектов типа ystok.uri:uri, представляющих якоря, т.е. во внимание принимается только фрагмент.
Значение

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

Описание

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

Если ни один из якорей не найден в книге, возвращается пустой список (), т.е. 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-a item &key class suffix

Аргументы
item
Абстрактный объект, обычно передаётся значение шаблонной переменной item внутри списка ссылок.
class
Имя CSS-класса, который будет приписан HTML-элементу A.
suffix
Булево значение,
умолчание есть 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>