Создание chm файлов

Содержание

Данный документ содержит информацию о создании chm-файла на основе html-файла, сгенерированного reSt'ом. Информация предназначена для разработчиков документации к 1С++, и не должна включаться в набор пользовательской документации.

Подготовка сгенерированного reSt'ом html-файла к созданию chm-файла выполняется скриптом "html2chm.js". Основная задача скрипта - на основе оглавления документа и с учетом дополнительной разметки разбить один входной файл на несколько отдельных файлов - "топиков", с сохранением ссылок между частями документа, и подготовка всех необходимых для работы программы "HTML Help WorkShop" файлов:

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

Дальнейшая сборка chm-файла выполняется программой "hhc", входящей в "HTML Help Workshop".

Запуск скрипта и дальнейшая сборка

Для сборки chm-файлов в системе должны быть установлены:

Подготовка файлов chm-проекта выполняется командой:

cscript "путь к html2chm.js" //nologo "имя входного html-файла" ["каталог получаемого chm-файла"]

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

Скрипт сформирует в каталоге входного файла необходимые файлы, и файл chm-проекта с именем "Имя входного файла без расширения.hhp".

Скрипт НЕ ВЫПОЛНЯЕТ копирования "внешних" файлов (*.css, файлы картинок и тп) из каталога входного файла в каталог сборки.

Далее необходимо запусть программу hhc.exe:

hhc.exe "Путь к файлу chm проекта (.hhp)"

Лучший вариант выполнять сборку - поручить ее среде разработки. Для этого в дереве файлов правокликните свой текстовый файл и выберите в контекстном меню "Settings". В окне настройки выберите конфигурацию "Win32 CHM" и на вкладке "Custom build" введите, или просто скопируйте это из настроек соседних файлов:

Description:
Произвольный текст, который будет выводится при сборке файла
Commands:
set intname="$(IntDir)\$(InputName).html"
set hhpname="$(IntDir)\$(InputName).hhp"
set chmname="$(OutDir)\$(InputName).chm"
if exist %intname% del %intname%
rst2html.py --output-encoding=CP1251 "$(InputPath)" %intname%
if not exist %intname% (
    echo Error create %intname%
    exit 1
)
cscript "$(ProjDir)\html2chm.js" //nologo //d %intname% "$(OutDir)"
if not exist %hhpname% (
    echo Error create %hhpname% and project files
    exit 1
)
if exist %chmname% del %chmname%
if exist %chmname% (
    echo Error delete old %chmname%
    exit 1
)
hhc %hhpname% > nul
if not exist %chmname% (
    echo Error create %chmname%
    exit 1
)
call "$(IntDir)\$(InputName)del.bat"
del "$(IntDir)\$(InputName)del.bat"
exit 0
Outputs:
$(OutDir)$(InputName).chm

При необходимости отредактируйте опции запуска rst2html.py под свои требования.

Убедитесь, что путь к каталогу расположения hhc.exe (HTML Help WorkShop) добавлен в каталоги исполняемых файлов MS VC++:

Tools -> Options -> Directories -> Show directories for -> Executable Files

Там же должен быть добавлен и путь к каталогу расположения скрипта rst2html.py

Теперь можно осуществлять сборку chm-файла простой компиляцией исходного текстового файла.

Требования к входному файлу

ВАЖНО.
Скрипт определяет структуру секций документа, обрабатывая оглавление, созданное reSt'ом.

Для определения структуры секций документа входной файл ОБЯЗАН иметь заголовочную секцию с содержанием, которая станет корневым топиком chm-файла. Для этого начало файла должно быть оформлено примерно так:

*****************************
Общий заголовок документа
*****************************
.. contents:: Содержание
    :backlinks: none

Опционально некий общий текст о документе.

Тут пошли секции документа
--------------------------

Данный заголовок будет использован как заголовок для окна CHM View, а также появляться в колонке "Местонахождение" для найденных полнотекстовым поиском топиков. Само содержание будет удалено. Если вы хотите, чтобы на первой странице все-таки осталось содержание, просто вставьте директиву contents два раза.

Дополнительная разметка входного файла

Основная цель скрипта - разбитие входного файла на отдельные "топики", на основе структуры секций документа, созданной reSt'ом.

В каждую секцию может быть включена информация, управляющая формированием chm-файла. Данная информация представляет из себя xml-разметку, с корнем из элемента chminfo (chm-разметка). Если в секции нет chm-разметки, она наследуется от родительской секции, по определенным правилам. Разметка вставляется в генерируемый файл как комментарий, чтобы не влиять на отображение html-документа. Скрипт предварительно выделяет из комментариев эту разметку, и обрабатывает ее, ища в каждой секции документа один элемент chminfo. Предпочтительно вставлять разметку сразу после заголовка секции. Состав элементов chm-разметки в-целом произвольный, но скрипт обрабатывает только определенные, известные ему элементы.

Пример:

Секция документа
----------------------
..  <chminfo>
    </chminfo>

Текст секции.....

Кроме chm-разметки каждой секции, определено одно место для внесения общей chm-разметки, служащей для хранения повторяющихся фрагментов разметки, подставляемых затем вместо элемента insert, а также для хранения описания коллекции chm-файлов. Такая разметка должна хранится в <xml><common>. После обработки файла эта разметка удаляется из документа. Рекомендуется для файлов одной коллекции создавать один общий файл с общей разметкой, подключая его к каждому файлу директивой include.

Этапы обработки html-файла скриптом

Работу скрипта можно разделить на несколько этапов:

Подготовка входного файла

Входной файл готовится к загрузке в MSXML парсер. При этом в тексте файла производится замена codepage CP1251 на windows-1251, и убираются комментарии вокруг chminfo. Затем файл загружается в MSXML парсер. Вся дальнейшая работа с файлом выполняется только через него. Из входного файла удаляются все комментарии, и производится обработка переходов по *alink* и *klink*.

Обработка оглавления

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

  • Находится либо создается chm-разметка секции.
  • Производится обработка элементов insert в chm-разметке.
  • Выполняется наследование chm-разметки дочерними секциями от их родителей.
  • Определяется необходимость вынесения секции в отдельный топик.
  • Определяется имя файла, в котором будет находится секция.
  • Исправляются ссылки в документе на содержимое секции с учетом нового имени файла, в котором будет находится секция.

Обработка секций

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

Подготовка файлов chm-проекта

Когда все секции обработаны, скрипт формирует файлы, необходимые программе "HTML Help Workshop" для сборки chm-файла.

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

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

Работа с chm-разметкой

Разбитие на топики

При обработке файла каждая секция документа является кандитатом на вынесение ее в отдельный топик. Будет ли она вынесена, определяется следующим образом:

  1. В chminfo есть атрибут "split"
    • ДА - п.2
    • НЕТ - п.3
  2. атрибут split="0"
    • ДА - не выносится
    • НЕТ - выносится
  3. В родительской секции в chminfo есть атрибут "splitchild"
    • ДА - п.4
    • НЕТ - п.5
  4. splitchild="0"
    • ДА - не выносится
    • НЕТ - выносится
  5. Родительская секция вынесена в отдельный топик
    • ДА - выносится
    • НЕТ - не выносится

Для корневой секции всегда считается, что она выносится в отдельный топик.

Вставки общей chm-разметки

Для избавления от необходимости прописывать одинаковые фрагменты разметки во многих местах, имеется возможность ее подстановки с помощью элемента insert. Целесообразно разместить фрагменты такой разметки либо в общий файл в раздел <xml><common>, либо в разметку корневой секции, в элемент nochilds.

См. также|collection_processing

Наследование разметки

При первоначальной обработке chm-разметки секций документа, на этапе обработки оглавления, происходит выполнения "наследования" элементов chm-разметки дочерней секцией от ее родительской секции. Даже если в самой секции не указан chminfo, скрипт все равно создает его, наследуя его от родителя. Наследование в данном случае обозначает просто копирование элементов, входящих в chminfo родительской секции.

Наследование выполняется по следующим правилам:

  1. Переопределение. От родителя наследуются только элементы, не указанные в самой секции.

    Например, если в секции есть элемент decoration, то копирование этого элемента из родительской секции не произойдет.

  2. Наследуются только элементы - непосредственные потомки chminfo.

    Например:

    Секция родитель:
        <chminfo>
            <decoration>
                <title to="selfremove"/>
            </decoration>
        </chminfo>
    
    Секция потомок:
        <chminfo>
            <decoration>
            </decoration>
        </chminfo>
    

    Элемент decoration/title не унаследуется.

  3. Исключение из правила 2. В родительской разметке может быть определен элемент childs, непосредственные потомки которого участвуют в наследовании, причем в первую очередь, копируясь в дочернюю разметку потомком chminfo. Правило 1. соблюдается.

    Например:

    Секция родитель:
        <chminfo>
            <decoration>
                <title to="selfremove"/>
            </decoration>
            <childs>
                <decoration>
                    <title to="parent"/>::<title to="selfremove"/>
                </decoration>
            </childs>
        </chminfo>
    
    Секция потомок до обработки:
        <chminfo>
        </chminfo>
    
    Секция потомок после обработки:
        <chminfo>
            <decoration>
                <title to="parent"/>::<title to="selfremove"/>
            </decoration>
        </chminfo>
    
  4. Не наследуются элементы:

  5. Все остальные элементы-потомки chminfo участвуют в наследовании.

Подстановочные элементы и атрибуты

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

Это такие элементы как

Кроме того, производится обработка элемента <a> (гиперссылка) с атрибутом href, равным предопределенным значениям.

Например:

<title to="parent"/>

будет заменен на текст заголовка родительской секции, а

<a href="next">Следующий</a>

будет заменен на

<a href="имя файла со следующим топиком">Следующий</a>

См. также|subst_processing

Задание ключевых слов и гиперссылок между файлами

В системе chm возможно задание двух видов ключевых слов: klink и alink.

klink - ключевые слова, выносимые в индексный указатель справки, и могущие быть привязаны не только к конкретной странице, но и местоположению (якорю) не ней. Таким образом, их можно использовать и для секций, не выносимых в топики.

alink - целевые слова, невидимые пользователю, и служащие для организации разработчиком навигации между топиками. Их можно привязать только к странице справке, те к топику в целом.

С помощью alink и klink можно организовывать навигацию типа "Смотри также", при этом навигация возможна не только в отдельном chm-файле, но и между файлами, входящими в коллекцию.

Работает это так:

Например, разработчик помечает несколько взаимосвязанных топиков одним и тем же целевым словом (alink). Затем он может вставить гиперссылку определенного вида, при нажатии на которую chm-просмотрщик отберет все топики, содержащие заданные ключевые слова, и предложит их пользователю, для перехода в них. Если будет найден только один топик, сразу будет совершен переход на него. Топики с заданными ключевыми словами ищутся во всех файлах коллекции. Таким образом, если вы хотите организовать переход из своего топика в топик другого файла, вставьте в другом топике уникальный alink, а у себя ссылку на него.

Ключевые слова для топика задаются элементами alinks и klinks. Также при наличии в chminfo элемента autokw возможна автоматическая генерация ключевых слов.

Для организации ссылки, работающей с ключевыми и целевыми словами, вставьте ссылку в таком виде:

для перехода по klink
`Текст ссылки|Ключевое слово1[|Еще ключевые слова...] <klink>`_

для перехода по alink
`Текст ссылки|Ключевое слово1[|Еще ключевые слова...] <alink>`_

Пример организации перехода между разными файлами:

файл 1...

Очень интересный топик
-------------------------
.. <chminfo>
     <alinks>_the_best_topic_</alinks>
   </chminfo>

Текст топика

Файл 2...

Хотите посмотреть `самый интересный раздел|_the_best_topic_ <alink>`_?

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

"имя файла.chm::/адрес внутри chm"

Например:

`Объект ТабличноеПоле <TableField.chm::/TableField0.html>`_

См. также|process_keywords

Формирование ссылок на выносимые топики

При вынесении секции документа в отдельный топик существует возможность задать в ее chm-разметке правила формирования ссылки на нее в родительском топике, как и задать правила объединения ссылок в самой секции на вынесенные из нее топики.

Формированием ссылки на выносимый топик управляет элемент href в разметке выносимой секции. Он представляет из себя "контейнер" html-кода, в котором с помощью подстановочных элементов и атрибутов и формируется ссылка. Например:

<href>
    <div>Перейти: <a href="self"><span style="color:red"><title to="self"/></span></a></div>
</href>

При обработке секции сформированный внутри href html код будет вставлен в родительской секции вместо выносимого топика. Естественно, если href пуст, то ссылки не будет.

Объединением ссылок на вынесенные топики управляет элемент hrefcombine в секции, в которой производится объединение. Элемент также представляет из себя контейнер html кода, в котором должны присутствовать элементы foreach и item. Скрипт собирает в секции документа блоки ссылок на вынесенные топики (ссылки, между которыми более ничего нет), и заменят их на содержимое hrefcombine, при этом для каждой ссылки в блоке "клонируется" элемент foreach, в котором элемент item заменяется на ссылку. Таким образом можно объединять рядомстоящие ссылки в списки и таблицы. Например:

<hrefcombine>
    <ul>
        <foreach>
            <li><item/></li>
        </foreach>
    </ul>
</hrefcombine>

См. также|href_processing

Обработка узла оглавления для секции

За формирование узла оглавления секции отвечают необязательные элементы cnttitle и toc.

cnttitle задает правило формирования строки в оглавлении для данной секции. Те текст содержимого этого элемента и будет строкой в оглавлении. При отсутствии этого элемента в оглавлении будет использоваться заголовок секции.

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

Содержимым элемента toc могут быть:

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

Пример 1:

<toc>
    <self>
        <childs/>
        <folder name="Дополнительные материалы">
            <merge file="addon1"/>
            <merge file="addon2"/>
        </folder>
    </self>
</toc>

Создаст в оглавлении папку с именем секции, в ней оглавление дочерних секций, вслед за ними папку с именем "Дополнительные материалы", в которой будут выведены оглавления файлов addon1.chm и addon2.chm.

Пример 2:

<toc>
    <self/>
</toc>

Подавит вставку оглавления дочерних секций, как например сделано в Этапы обработки html-файла скриптом

Пример 3:

<toc>
    <self>
        <childs/>
    </self>
    <merge file="other"/>
</toc>

Вставит в оглавлении после секции оглавление файла other.chm

Пример 4:

<toc>
    <folder name="Раздел 4">
        <self>
            <childstoc/>
        </self>
        <folder name="Раздел 4.2">
            <merge file="volume4_2"/>
        </folder>
    </folder>
</toc>

Задание html-заголовка топика

При вынесении секции в отдельный топик возможно задать для нее текст <head><title>, который будет являтся заголовком топика в различных диалоговых окнах chm-просмотрщика, что зачастую более информативно, чем простой заголовок секции.

Выполняется это заданием элемента chmtitle, текст содержимого которого и будет заголовком топика. При отсутствии этого элемента, в качестве заголовка топика будет использоваться строка его оглавления.

Обрамление топика

При сохранении секции в файл существует возможность задать обрамление топика с помощью элемента decoration, который представляет собой контейнер html-кода, в котором будут выполнены замены подстановочных элементов и атрибутов, а вместо содержащегося в нем элемента topic будет вставлен текст выносимого топика.

Работа с коллекциями chm-файлов

Информация о вхождении файла в коллекцию chm-файлов должна располагатся в месте расположения общей информации, <xml><common>. Там она представлена элементом collection. В нем указывается мастер-файл коллекции, и перечисляются файлы, входящие в нее.

Оглавление мастер-файла и его начальная страница будут указаны как оглавление и начальная страница для всех файлов коллекции.

См. также|collection_processing

Справка по элементам

chminfo

Является корневым элементом chm-разметки секции. Обрабатывается один элемент chminfo на каждую секцию.

Атрибуты:
[split]
при "0" секция не выделяется в отдельный топик.
[splitchild]
задает значение по умолчанию атрибута split в элементах chminfo дочерних секций.
Обрабатывается:
один элемент chminfo, непосредственный потомок элемента секции документа.
Дочерние элементы:
любые.

При отсутствии в секции документа chminfo, считается пустым. Для каждого элемента chminfo производится наследование его содержимого от chminfo родительской секции. Атрибуты split и splitchild управляют разбитием документа на отдельные топики.

autokw

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

Атрибуты:
mode

задает режим обработки заголовка секции. Является битовой комбинацией следующих значений:

  • 1 - Заголовок секции целиком добавляется в индексный указатель. (Из заголовка удаляются символы ",")
  • 2 - Заголовок секции разделяется на отдельные слова, каждое из которых добавляется в индексный указатель. Разделение происходит по символам: Пробел, "," ";" ":" "/" "\"
  • Другие значения атрибута не вызывают никаких действий.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
нет.

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

См. также|process_keywords

alinks

Задает состав целевых слов секции документа.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
Текст ключевых слов.

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

Допускается указывать несколько ключевых слов, разделитель - перевод строки.

См. также|process_keywords

klinks

Задает состав ключевых слов секции документа.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
Текст ключевых слов.

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

Допускается указывать несколько ключевых слов, разделитель - перевод строки.

Возможно создание "многоуровневых" ключевых слов. Каждый уровень отделяется от другого запятой. Например:

<klinks>
    Элемент
    Элемент, chminfo
    Элемент, childs
</klinks>

Создаст в индексе следующую запись:

Элемент
    chminfo
    childs

См. также|process_keywords

decoration

Задает html-обрамление топика.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
html-разметка, topic, subst, title.

Данный элемент является "контейнером" html-кода, которым будет обрамлен топик при сохранении его в файл, и являтся составом тэга <BODY> html-файла. Место вставки топика внутри элементов decoration задается элементом topic. При его отсутствии, топик будет добавлен в конце decoration.

Внутри элемента выполняется обработка подстановочных элементов и атрибутов.

topic

Задает место вставки сохраняемого топика внутри элемента decoration.

Атрибуты:
нет.
Обрабатывается:
в любом месте обрабатываемого decoration.
Дочерние элементы:
нет.

href

Задает правило создания ссылок на секцию, выносимую в топик.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
html-разметка, subst, title.

После обработки подстановочных элементов и атрибутов внутри элемента, его содержимое будет вставлено в родительской секции вместо выносимой секции.

См. также|href_processing

hrefcombine

Задает правила объединения ссылок на вынесенные секции.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
html-разметка, subst, title, foreach, item.

Внутри элемента выполняется обработка подстановочных элементов и атрибутов.

Ссылки на вынесенные cекции разделяются на "непрерывные" блоки, то есть одну или более идущих подряд ссылок. Каждый такой блок заменяется содержимым hrefcombine, причем для каждой ссылки в блоке будет клонировано содержимое элемента foreach, в котором элемент item будет заменен на саму ссылку.

См. также|href_processing

foreach

Задает повторяющийся для каждой ссылки на вынесенный топик html-код в содержимом элемента hrefcombine.

Атрибуты:
нет.
Обрабатывается:
в любом месте обрабатываемого hrefcombine
Дочерние элементы:
html-разметка, subst, title, item.

Внутри элемента выполняется обработка подстановочных элементов и атрибутов.

item

Задает расположение ссылки на вынесенный топик в содержимом элемента foreach.

Атрибуты:
нет.
Обрабатывается:
в любом месте обрабатываемого foreach
Дочерние элементы:
нет.

childs

Содержит элементы, которые должны быть унаследованы дочерними секциями в первую очередь.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
любые.

Непосредственные потомки элемента childs будут участвовать в наследовании разметки в первую очередь, переносясь в дочерние секции непосредственными потомками chminfo этих секций. Это позволяет в разметке одной секции задать разное содержимое одинаковых элементов для себя и дочерних секций.

Сам элемент childs не наследуется.

nochilds

Не наследуемый элемент разметки.

Атрибуты:
нет.
Обрабатывается:
нет.
Дочерние элементы:
любые.

Элемент является контейнером для элементов, которые вы не хотите наследовать дочерними секциями. Наиболее целесообразно размещать здесь пользовательские элементы, подставляемые в другие места разметки элементами insert и subst.

chmtitle

Задает содержимое тэга <head><title> формируемого файла топика.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
текст, title, subst.

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

Элемент не обязателен. При его отсутствии или если в нем нет текста, значением заголовка топика становится строка из оглавления для топика, задаваемая элементом cnttitle.

cnttitle

Задает строку для оглавления данной секции в chm-файле.

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
текст, title, subst.

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

Элемент не обязателен. При его отсутствии или если в нем нет текста, значением названия секции в оглавлении становится название секции.

toc

(Table Of Contents)

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

Атрибуты:
нет.
Обрабатывается:
только когда является непосредственным потомком chminfo.
Дочерние элементы:
self, folder, merge, childstoc.

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

Элемент не обязателен. При его отсутсвии в оглавление вставляется ссылка на секцию и входящие в нее ссылки на дочерние секции.

self

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

Атрибуты:
нет.
Обрабатывается:
только когда является потомком toc.
Дочерние элементы:
folder, merge, childstoc.

При отсутствии элемента self в элементе toc, доступ к секции из оглавления невозможен.

childstoc

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

Атрибуты:
нет.
Обрабатывается:
только когда является потомком toc.
Дочерние элементы:
нет.

При отсутствии элемента childstoc в элементе toc, доступ к дочерним секция из оглавления невозможен.

folder

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

Атрибуты:
name - Задает имя создаваемого узла.
Обрабатывается:
только когда является потомком toc.
Дочерние элементы:
self, folder, merge, childstoc.

merge

Вставляет ссылку на оглавление другого chm-файла при формировании узла оглавления для данной секции.

Атрибуты:
file - Задает имя другого chm-файла, оглавление которого должно быть вставлено, без расширения chm.
Обрабатывается:
только когда является потомком toc.
Дочерние элементы:
нет.

insert

Подстановочный элемент.

Атрибуты:
node
Содержит выражение на языке XPath, применяемое в методе selectSingleNode к элементу chminfo.
nodes
Содержит выражение на языке XPath, применяемое в методе selectNodes к элементу chminfo.
asxml
При задании равным "1" вместо результата выборки будет вставлен текст, равныйй xml-коду выборки.
Обрабатывается:
В любом месте chminfo
Дочерние элементы:
нет.

Элемент применяется для вставки на свое место содержимого других элементов документа. Целесообразно применять его для вынесенения повторяющихся кусков chm-разметки в общее место, с тем чтобы потом применять их в разных местах. Например:

Определим в корневой секции:
<chminfo>
    ...
    <nochilds>
        <decorformethods>
            <decoration>
                ....
            </decoration>
        </decorformethods>
    </nochilds>
</chminfo>

Затем в некоторых секциях:
<chminfo>
    <insert node="//decorformethods/*"/>
</chminfo>

Допустимо указывать оба атрибута, node и nodes одновременно. Тогда элемент будет заменен результатом двух выборок.

В отличии от элемента subst, insert обрабатывается при начале обработки chminfo, до выполнения наследования. Таким образом, сначала будет обработан insert, заменен результатом выборок, и дочерними секциями элемент наследоватся не будет.

При обработке элемента возможно, что в результате выборки снова будут элементы insert. Чтобы избежать зацикливания, вновь появившиеся элементы insert, содержащие выражения для выборок, уже использовавшиееся в обработке, не обрабатываются.

См. также|subst_processing

subst

Подстановочный элемент.

Атрибуты:
node
Содержит выражение на языке XPath, применяемое в методе selectSingleNode к узлу секции.
nodes
Содержит выражение на языке XPath, применяемое в методе selectNodes к узлу секции.
asxml
При задании равным "1" вместо результата выборки будет вставлен текст, равныйй xml-коду выборки.
Обрабатывается:
В любом месте секции.
Дочерние элементы:
нет.

Элемент применяется для вставки на свое место содержимого других элементов документа. Целесообразно применять его для задания в разметке родительских секций мест, которые возможно будут переопределены в дочерних секциях. Например:

Определим в корневой секции:
<chminfo>
    <decoration>
        <table>
            <tr>
                <td>Секция:</td>
                <td><subst nodes="topictitle/node()"/></td>
            </tr>
        </table>
    </decoration>
    <topictitle><title to="self"/></topictitle>
</chminfo>

Так как <topictitle> наследуется дочерними секциями, в них вместо subst подставится <title to="self"/>. Однако можно в некоторых дочерних секциях переопределить <topictitle>, изменив часть унаследованного элемента decoration:

<chminfo>
    <topictitle>
        <a href="parent"><title to="parent"/></a>::<title to="self"/>
    </topictitle>
</chminfo>

Допустимо указывать оба атрибута, node и nodes одновременно. Тогда элемент будет заменен результатом двух выборок.

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

Кроме того, применение выражений в node и nodes выполняется не к элементу chminfo, а к узлу секции.

При обработке элемента возможно, что в результате выборки снова будут элементы subst. Чтобы избежать зацикливания, вновь появившиеся элементы subst, содержащие выражения для выборок, уже использовавшиееся в обработке, не обрабатываются.

См. также|subst_processing

title

Подставляет вместо себя заголовок секций.

Атрибуты:
to

указывает, заголовок какой секции подставлять. Допускается:

  • self - Заголовок самой секции
  • selfremove - Заголовок самой секции c его удалением
  • next - Заголовок следующего топика
  • prev - Заголовок предудущего топика
  • home - Заголовок корневой секции
  • parent, parent[уровень] - Заголовок родительской секции заданного уровня. Нумерация уровней с нуля, те parent == parent[0]
Обрабатывается:
в любом месте chminfo
Дочерние элементы:
нет.

Служит для задания текста в участках html-кода. Если при обработке секции встретился хотя бы один элемент title с атрибутом to равным "selfremove", то сам заголовок из секции удаляется.

См. также|subst_processing

a

Здесь рассматривается элемент "a" html-разметки (anchor, гиперссылка), появляющийся в элементах-контейнерах html-кода chm-разметки, и содержащий атрибут href, равный предопределенным значениям. Этот атрибут заменяется на значения, исходя из контекста обрабатываемой секции.

Предопределенные значения атрибута href:
self
Заменяется на адрес самой секции. Целесообразно применять в элементе href
next
Заменяется на адрес следующего топика
prev
Заменяется на адрес предыдущего топика
home
Заменяется на адрес корневого топика
parent, parent[уровень]
Заменяется на адрес родительской секции заданного уровня. Нумерация уровней с нуля, те parent == parent[0]

Кроме того, во всем документе допустимо указание атрибута href, равного "alink" и "klink". Для таких элементов будет добавлен объект "HHCtrl", реализующий соответственно, переход по ALink или KLink, для ключевых слов, указанных в тексте ссылки. См. Задание ключевых слов и гиперссылок между файлами.

При обработке элемента chmlinks, атрибут href, равный "click", заменяется на код активизации объекта "HHCtrl"

См. также|subst_processing

chmlinks

Создает объект HHCtrl, для организации ALink и KLink.

Атрибуты:
type
Задает тип объекта. Может принимать два значения: - ALink - KLink
Обрабатывается:
в любом месте chminfo.
Дочерние элементы:
html-разметка, keys.

Элемент создает объект chm-справки HHCtrl, служащий для организации перехода по ALinks или KLinks, по заданным ключевым словам. Слова задаются в элементе keys. Если этот элемент отсутствует, или пуст, все содержимое chmlinks исключается из разметки.

В составе html-разметки должен присутствовать элемент 'a' с атрибутом href, равным "click". Именно эта ссылка будет активировать объект.

keys

Перечисляет ключевые слова для chmlinks

Атрибуты:
нет.
Обрабатывается:
только внутри обрабатываемого chmlinks
Дочерние элементы:
Текст ключевых слов.

Ключевые слова разделяются переводом строки.

common

Задает узел для хранения общей информации.

Атрибуты:
нет.
Обрабатывается:
только внутри элемента xml.
Дочерние элементы:
Любые.

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

Достигается это созданием одного файла, следующего содержания:

.. raw:: html
    <xml><common>
    ...
    </common></xml>

и дальнейшим включением этого файла во все файлы коллекции директивой include:

*************************************
Общий заголовок документа
*************************************

Директива ..raw применяется для того, чтобы в данном элементе спокойно вставлять xml-комментарии, а <xml> - чтобы информация не отображалась при тестировании html-файла, без сборки chm.

При сборке chm узел <xml>, содержащий <common>, будет удален из конечного файла.

Для описания коллекции в common используется элемент collection.

См. также|collection_processing

collection

Содержит информацию о коллекции chm-файлов.

Атрибуты:
master
Задает основной файл коллекции.
title
Задает имя коллекции, которое будет заголовком окна справки.
Обрабатывается:
только когда является непосредственным потомком common.
Дочерние элементы:
file.

Коллекция chm-файлов - это несколько отдельных файлов, работающих как одно целое. У них общее оглавление, общий индексный указатель, полнотекстовый поиск и alinks. Один из файлов является основным, именно его оглавление и будет общим для всех файлов, и должно включать в себя ссылки на оглавления других файлов.

Входящие в collection элементы file задают состав файлов коллекции. При задании имен файлов из следует указывать без расширения, с учетом регистра имен.

См. также|collection_processing

file

Задает файл коллекции.

Атрибуты:
name
Указывает имя файла без расширения, с учетом регистра.
Обрабатывается:
только когда является непосредственным потомком collection.
Дочерние элементы:
нет.

См. также|collection_processing