Якоря и гибкие ссылки: схема help

Якоря и гибкие ссылки: схема `help`

Статья книги может содержать перекрёстные ссылки как на другие статьи, так и внешние ресурсы. Поддержание внутренних ссылок облегчают якоря и гибкие ссылки на них. Благодаря схеме help, автору книги не обязательно знать, в каком файле будет окончательно расположен фрагмент текста: компилятор YstokHelp заменит имена фрагментов на реальные ссылки.

Якорем называется символическое имя, которое вводится следующими элементами HTML:

A с помощью атрибута name="anchor_name",
DFN или DT с помощью атрибута id="anchor_name",
заголовочными элементами Hi с помощью атрибута id="anchor_name".

Будем говорить, что якорь определён в данном HTML элементе. Якорь выполняют двойную функцию:

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

Синтаксис anchor_name регламентируется стандартом HTML:

имя должно начинаться с латинской буквы A-Z или подчёркивания (_);
затем могут следовать латинские буквы, цифры 0-9, дефис (-), точка (.) или двоеточие (:);
регистр букв заглавные/строчные важен;
пробелы в открытую не разрешены, но их можно включить в имя при помощи %-кодированных последовательностей (percent-encoding);
буквы национальных алфавитов могут допускаться наряду с латинскими при настройке локализации.

Гибкая ссылка в исходном HTML-файле на якорь задаётся в следующем виде
<A href="help:...">
Гибкая ссылка может включать идентификаторы книг и разделов, имена якорей, содержать литеры допустимые спецификацией URI. Запрещено использование пробелов и букв национальных алфавитов (кроме как внутри части фрагмента). Однако такие литеры могут быть вставлены при помощи %-кодирования.

"help:#anchor_name"
"help://book_id#anchor_name"
"help:/chapter_name#anchor_name"
"help://book_id/chapter_name#anchor_name": Перейти на страницу и фрагмент, задаваемые якорем, в указанной книге. Если идентификатор книги book_id не задан, то якорь ищется в текущей книге. Путь в виде одного или более имён chapter_name, разделённых знаком /, позволяет сузить множество возможных адресатов: якорь ищется только среди потомков указанного раздела/подраздела. Указание пути может быть полезно, когда определены два или более якоря с одним и тем же именем, но в разных разделах.
"help://book_id"
"help://book_id/chapter_name/"
"help:/chapter_name/": Перейти на начальную страницу книги или раздела. Если идентификатор книги не задан, то раздел ищется в текущей книге.
"help://book_id/path/filename.ext": Ссылка на ресурс, обычно на файл в папке раздела или файл во вспомогательной папке. Путь path вычисляется в первую очередь по именам разделов и подразделов, и лишь во вторую — по именам физических папок.

Примеры

"help://my-book/chapter-one/index.html": Путь через имя главы chapter-one.
"help://my-book/gfx/image.png": Путь к файлу во вспомогательной папке gfx.
"help://my-book/chapter-one/gfx/index.html": Путь к файлу во вспомогательной папке внутри раздела.

Компилятор "проходит" по гибким ссылкам, осуществляя контроль за компонентами, в которые они ведут. Напротив, если исходная гиперссылка задана стандартным образом, т.е. в виде
<A href="http://...">
или без указания схемы, то компилятор не пытается ни анализировать, ведёт ли ссылка к существующему файлу, ни искать соответствующий компонент книги, ни открывать указанный файл!