Компилятор предметного указателя

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

Чтобы создать предметный указатель, следует поместить в определение книги помощи компонент типа index.

Ключевые фразы

Ключевая фраза вводится на любой статейной странице якорем — одним из следующих элементов HTML:

Атрибут name или id обязателен для определения якоря.

Когда атрибут help не задан или в нем отсутствует свойство keywords, то ключевая фраза определяется содержимым HTML-элемента, заключённым между открывающим и закрывающим тегами. Если это содержимое пусто, якорь ничего не вносит в предметный указатель, а служит только в качестве точки перехода. Если не пусто, первая буква text переводится в нижний регистр, что и даёт ключевую фразу.

Когда в атрибуте help задано свойство keywords, то его значение keyword-list может быть одним из следующих:

keyword[,keyword]...
Список фраз, которые помещаются в предметный указатель и ассоциируются с данным якорем; фразы разделяются запятыми и берутся буквально, без преобразования регистра букв, а text в этом случае игнорируется и может быть пустым.
none, nil или пустая строка (пустое свойство)
Ничего не вносить в предметный указатель, даже если содержимое элемента не пусто.

Происходит индексация всех слов фразы, кроме служебных, а также слов, заключенных в круглые (), квадратные [] или фигурные {} скобки.

Например, пусть фраза, поступившая из text или keyword, есть

слово (с фразой в скобках)"

Из её составляющих в указатель будет помещён только вход "слово", а подфраза в скобках не индексируется.

Категория фразы является меткой, которая печатается в предметном указателе вслед за самой ключевой фразой или термином.

Необходимым условие такой выдачи — ключ CATEGORY должен фигурировать в списке '>.

Пример
<dfn id="CREATE-INDEX" help="category:[функция]">create-index</dfn>

приводит к следующей строке в предметном указателе:

create-index [функция 1]

Избегайте определять якоря в коде под условной ветвью шаблона YHTML-Template. Есть вероятность, что такой код будет отсечён на фазе компиляции статьи, но якорь тем не менее попадет в предметный указатель!
Причина: на фазе сбора якорей условные директивы игнорируются (в данной версии компилятора).

Служебные слова

Предметный указатель индексирует каждую ключевую фразу по словам, из которых она состоит. Слова отделяются друг от друга пробелами, дефисами или другими знаками пунктуации (кроме ',' и ';').

К служебным словам (stopwords) относятся предлоги, междометья, общеупотребимые наречия и т.п. Индексация по таким словам не происходит.

Файлы со служебными словами:

Эти файлы подгружаются автоматически при запуске компилятора предметного указателя (т.е. при вызове функции create-index).

[класс] index

Аннотация

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

Пакет

ystok.help

Надклассы

navigation-mixin, generated-component

Ключевые аргументы :option value
tab
Строка, задающая надпись на ярлычке, например, "Указатель".
type
Тип, единственно допустимое в версии значение есть :permuted (умолчание), что означает перестановочный указатель.
multipage
Если истина, то предметный указатель состоит не из одного файла idx.html, а из набора файлов страниц. Умолчание есть nil.
letters
Строка из букв-представителей алфавита, на которые разбивается предметный указатель.
Умолчание вычисляется исходя из алфавита языка книги.
stopwords-language
Код (строка или ключ) или список кодов языков, которые рассматриваются при проверке, не является ли слово служебным. Если не задан, по умолчанию используется код языка книги.
max-left-chars
Ширина левого столбца каждой страницы перестановочного индекса, имеет смысл только для типа :permuted.
Умолчание задаётся параметром *default-index-max-left-chars*.
Описание

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

Имя компонента задаёт имя файла предметного указателя, помещаемого в корень целевой папки книги. Если предметный указатель многостраничный, то данный аргумент задает префикс к имени файла, а полное имя файла получается конкатенацией префикса с суффиксом — буквой, на которую приведены термины данной страницы, например: idx_A.html - на букву А, idx_B.html - на букву Б и т.д.

Список таких букв-представителей можно указать в аргументе letters. В качестве последней литеры обычно указывается знак *, означающий "все прочие буквы". Если предметный указатель одностраничный, то аргумент задаёт подзаголовки на странице указателя.

[функция] create-index

Сигнатура

create-index book-name-or-system &key type multipage =>

Пакет

ystok.help

Аргументы
book-name-or-system
Разрабатываемая книга помощи — экземпляр класса book-system — или имя книги.
type, multipage
См. описание аргументов класса index выше.
Возвращаемые значения

Нет.

Описание

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

Компилятор предметного указателя создает

Запуск компилятора указателя происходит автоматически при комплиляции всей книги.

Перестановочный указатель

Предметный указатель с типом :permuted формируется по всем словам кроме служебных.

Сколько слов во фразе за исключением служебных, столько раз фраза будет фигурировать в перестановочном указателе.

Фразы выравниваются по началу каждого из слов, а левая часть фразы, если она слишком длинная, сокращается. Наибольшая число выдаваемых в левой части литер определяется аргументом max-left-chars.

Примеры

Фраза "определение книги помощи" будет фигурировать под следующими буквами:

под буквой К
определение книги помощи
под буквой О
определение книги помощи
под буквой П
определение книги помощи