Бывает, планируется разбить статью на большое число страниц. При редактировании, однако, бывает удобнее держать её в виде одного HTML-файла, нежели работать со множеством отдельных файлов страниц. Достичь этого можно маркировкой сегментов исходного файла.
Каждый разделитель сегмента представляет собой псевдотег вида:
<!-- HELP_SEGMENT [property-list [примечание]] -->
Нулевой сегмент начинается с открывающего тега
<BODY>
и тянется до первого разделителя сегмента.
Его заголовок, описание и ключевые слова задается метаэлементами в элементе
HEAD файла,
см. Статейная страница.
Первый сегмент начинается сразу после первого разделителя, а самый последний тянется
от последнего разделителя до закрывающего тега </BODY>.
Для сегментов, кроме нулевого, можно указать property-list —
список свойств в круглых скобках (согласно языку Лисп).
В нём допускаются свойства
:title, :description, :keywords
и :braces.
Если свойство :title отсутствует в списке,
компилятор YstokHelp подставит в качестве него содержимое самого первого в сегменте
заголовочного элемента.
Свойство :braces
позволяет в одном сегменте файла интерпретировать фигурные скобки
как ограничители выражения шаблона,
а в другом — как обычные литеры. Если свойство отсутствует, то
умолчание берётся
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") --> ...