Сегменты: разбиение исходных файлов на страницы

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

Каждый разделитель сегмента представляет собой псевдотег вида:

<!-- HELP_SEGMENT [property-list [примечание]] -->

Нулевой сегмент начинается с открывающего тега <BODY> и тянется до первого разделителя сегмента. Его заголовок, описание и ключевые слова задается метаэлементами в элементе HEAD файла, см. Статейная страница. Первый сегмент начинается сразу после первого разделителя, а самый последний тянется от последнего разделителя до закрывающего тега </BODY>.

Для сегментов, кроме нулевого, можно указать property-list — список свойств в круглых скобках (согласно языку Лисп). В нём допускаются свойства :title, :description, :keywords и :braces.

Если свойство :title отсутствует в списке, компилятор YstokHelp подставит в качестве него содержимое самого первого в сегменте заголовочного элемента.

Свойство :braces позволяет в одном сегменте файла интерпретировать фигурные скобки как ограничители выражения шаблона, а в другом — как обычные литеры. Если свойство отсутствует, то умолчание берётся

Компилятор сам разобьёт исходный файл на несколько отдельных файлов страниц. В целевой папке они будут поименованы src_name_00.html, src_name_01.html и т.д.

Как следствие, нежелательно задавать переходы на якоря внутри разбиваемой на сегменты статьи путём "жёстких ссылок":
 "src_name.html#anchor_name"

Вместо этого следует применять гибкие ссылки:
 "help:#anchor_name"

Внимание: Разделители сегментов должны появляться на самом верхнем уровне тела документа, т.е. непосредственно внутри <BODY>. Они не обеспечивают автоматического закрытия прочих тегов. Например, незакрытый явным образом тег <P> приведёт к тому, что компилятор пропустит последующий разделитель сегмента!

Пример
...
<!-- HELP_SEGMENT (:title "YstokHelp in Simple"
  :description "Base features of YstokHelp"
  :keywords "simple,feature,open") -->
<h1>How to open YstokHelp book</h1>
<p>To open an YstokHelp book, ... </p>
<!-- HELP_SEGMENT (:title "YstokHelp in Details"
  :description "Advanced features of YstokHelp"
  :keywords "advanced,detail,feature") -->
...
Примеры разделённых на сегменты исходных статей