.. Автор: Александр Орефков

************************
Создание chm файлов
************************
..  <chminfo>
        <decoration>
            <topic/>
            <a href="#" onclick="mychminfo.style.display=(mychminfo.style.display=='')?'none':''">chminfo данной секции</a>
            <pre id="mychminfo" style="display:none">
                <subst node="chminfo" asxml="1"/>
            </pre>
        </decoration>
        <alinks>_1cpp_chm_create_</alinks>
        <href>
            <a href="self"><title to="self"/></a>
        </href>
        <hrefcombine>
            <ul>
                <foreach><li><item/></li></foreach>
            </ul>
        </hrefcombine>
    </chminfo>

.. contents:: Содержание
    :backlinks: none

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

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

- html-файлы статей справки (*топиков*), на которые будет разбит основной html-файл
- Файл описания проекта (\*.hhp)
- Файл содержания (\*.hhc)
- Файл ключевых слов (\*.hhk)

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

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

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


Запуск скрипта и дальнейшая сборка
-----------------------------------
..  <chminfo>
        <klinks>
            Запуск
            сборка
        </klinks>
    </chminfo>

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

- MSXML парсер версии 4.0
- WSH 5.6
- HTML Help Workshop

Подготовка файлов 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-файла простой компиляцией исходного
текстового файла.


Требования к входному файлу
---------------------------
..  <chminfo>
        <klinks>
            Требования
        </klinks>
    </chminfo>


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

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

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

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

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

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


Дополнительная разметка входного файла
-----------------------------------------
..  <chminfo>
        <klinks>
            Разметка
        </klinks>
        <alinks>
            _split_topics_
            alink_klink_use
        </alinks>
    </chminfo>

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

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

Пример::

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

.. __ : `Наследование разметки`_

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


Этапы обработки html-файла скриптом
-------------------------------------------------
..  <chminfo splitchild="0">
        <toc><self/></toc>
    </chminfo>

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

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

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

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

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

.. __: `Наследование разметки`_
.. __: `Разбитие на топики`_

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

- Обработка элементов `subst`_ в chm-разметке секции.
- Раскрытие `подстановочных элементов и атрибутов`__ в chm-разметке секции.
- Обработка `ключевых слов`__, заданных для секции.
- Обработка `ссылок на дочерние секции`__, вынесенные из этой
  секции в отдельные топики.
- Подготовка `узла оглавления`__ chm-файла для этой секции.
- Если секция выносится в топик:

  - Формирование `ссылки на эту секцию`__, которая будет вставлена
    в родительскую секцию.
  - Определения `html заголовка`__ (title) топика.
  - Обработка `обрамления`__ топика.
  - Сохранение топика в файл.
  - Удаление топика из родительской секции, и замена его на
    сформированную ссылку.

.. __: `Подстановочные элементы и атрибуты`_
.. __: `Задание ключевых слов и гиперссылок между файлами`_
.. __: `Формирование ссылок на выносимые топики`_
.. __: `Обработка узла оглавления для секции`_
.. __: `Формирование ссылок на выносимые топики`_
.. __: `Задание html-заголовка топика`_
.. __: `Обрамление топика`_


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

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

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

.. __: `Работа с коллекциями chm-файлов`_


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

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

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

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

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

Вставки общей chm-разметки
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. <chminfo><alinks>collection_processing</alinks></chminfo>

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

`См. также|collection_processing <alink>`_

Наследование разметки
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
При первоначальной обработке 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>
#. Не наследуются элементы:
   
   - `alinks`_
   - `klinks`_
   - `nochilds`_
   - `toc`_

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


Подстановочные элементы и атрибуты
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
..	<chminfo><alinks>subst_processing</alinks></chminfo>

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

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

- `title`_
- `subst`_

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

Например::

  <title to="parent"/>

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

::

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

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

::

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


`См. также|subst_processing <alink>`_


Задание ключевых слов и гиперссылок между файлами
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
..  <chminfo><alinks>process_keywords</alinks></chminfo>

В системе 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 <alink>`_


Формирование ссылок на выносимые топики
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. <chminfo><alinks>href_processing</alinks></chminfo>


При вынесении секции документа в отдельный топик существует
возможность задать в ее 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 <alink>`_

Обработка узла оглавления для секции
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
За формирование узла оглавления секции отвечают необязательные
элементы `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-файлов
-----------------------------------------
.. <chminfo><alinks>collection_processing</alinks></chminfo>

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

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

`См. также|collection_processing <alink>`_

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


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

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

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

.. __ : `Наследование разметки`_
.. __ : `Разбитие на топики`_

autokw
~~~~~~~~~~~~~~~~~~~~~
..  <chminfo><alinks>process_keywords</alinks></chminfo>

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

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

**Обрабатывается:**
    только когда является непосредственным потомком `chminfo`_. 
**Дочерние элементы:**
    нет.
    
Наиболее целесообразно указывать этот элемент в составе элемента `childs`_
родительской секции, с тем чтобы этот атрибут был унаследован дочерними
секциями.

`См. также|process_keywords <alink>`_

alinks
~~~~~~~~~~~~~~~~~~~~~
..  <chminfo><alinks>process_keywords</alinks></chminfo>

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

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

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

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

`См. также|process_keywords <alink>`_


klinks
~~~~~~~~~~~~~~~~~~~~~
..  <chminfo><alinks>process_keywords</alinks></chminfo>

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

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

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

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

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

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

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

    Элемент
        chminfo
        childs

`См. также|process_keywords <alink>`_


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

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

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

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

.. __ : `Подстановочные элементы и атрибуты`_

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

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


href
~~~~~~~~~~~~~~~~~~~~~
.. <chminfo><alinks>href_processing</alinks></chminfo>

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

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

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

.. __ : `Подстановочные элементы и атрибуты`_

`См. также|href_processing <alink>`_

hrefcombine
~~~~~~~~~~~~~~~~~~~~~
.. <chminfo><alinks>href_processing</alinks></chminfo>

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

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

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

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

.. __ : `Подстановочные элементы и атрибуты`_

`См. также|href_processing <alink>`_


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
~~~~~~~~~~~~~~~~~~~~~~~~~~
..	<chminfo><alinks>subst_processing</alinks></chminfo>

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

**Атрибуты:**
    *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 <alink>`_

subst
~~~~~~~~~~~~~~~~~~~~~~~~~~
..	<chminfo><alinks>subst_processing</alinks></chminfo>

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

**Атрибуты:**
    *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 <alink>`_

title
~~~~~~~~~~~~~~~~~~~~~
..	<chminfo><alinks>subst_processing</alinks></chminfo>

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

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

        - self - Заголовок самой секции
        - selfremove - Заголовок самой секции c его удалением
        - next - Заголовок следующего топика
        - prev - Заголовок предудущего топика
        - home - Заголовок корневой секции
        - parent, parent[уровень] - Заголовок родительской секции заданного уровня.
          Нумерация уровней с нуля, те *parent* == *parent[0]*

**Обрабатывается:**
    в любом месте `chminfo`_
**Дочерние элементы:**
    нет.

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

`См. также|subst_processing <alink>`_

a
~~~~~~~~~~~~~~~~~~~~~
..	<chminfo><alinks>subst_processing</alinks></chminfo>

Здесь рассматривается элемент *"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 <alink>`_

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

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

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

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

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

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

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

common
~~~~~~~~~~~~~~~~~~~~~
.. <chminfo><alinks>collection_processing</alinks></chminfo>

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

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

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

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

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

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

    *************************************
    Общий заголовок документа
    *************************************
    .. include:: commonchm.txt

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

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

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

`См. также|collection_processing <alink>`_

collection
~~~~~~~~~~~~~~~~~~~~~
.. <chminfo><alinks>collection_processing</alinks></chminfo>

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

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

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

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

`См. также|collection_processing <alink>`_

file
~~~~~~~~~~~~~~~~~~~~~
.. <chminfo><alinks>collection_processing</alinks></chminfo>

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

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

`См. также|collection_processing <alink>`_
