]>

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

chminfo данной секции

_1cpp_chm_create_

Содержание

- Запуск скрипта и дальнейшая сборка
- Требования к входному файлу
- Дополнительная разметка входного файла
- Этапы обработки html-файла скриптом
  - Подготовка входного файла
  - Обработка оглавления
  - Обработка секций
  - Подготовка файлов chm-проекта
- Работа с chm-разметкой
  - Разбитие на топики
  - Вставки общей chm-разметки
  - Наследование разметки
  - Подстановочные элементы и атрибуты
  - Задание ключевых слов и гиперссылок между файлами
  - Формирование ссылок на выносимые топики
  - Обработка узла оглавления для секции
  - Задание html-заголовка топика
  - Обрамление топика
- Работа с коллекциями chm-файлов
- Справка по элементам
  - chminfo
  - autokw
  - alinks
  - klinks
  - decoration
  - topic
  - href
  - hrefcombine
  - foreach
  - item
  - childs
  - nochilds
  - chmtitle
  - cnttitle
  - toc
  - self
  - childstoc
  - folder
  - merge
  - insert
  - subst
  - title
  - a
  - chmlinks
  - keys
  - common
  - collection
  - file

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

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

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

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

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

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

Запуск сборка

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

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

Требования

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

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

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

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

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

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

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

Разметка _split_topics_ alink_klink_use

Основная цель скрипта - разбитие входного файла на отдельные "топики", на основе структуры секций документа, созданной 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-разметки дочерними секциями от их родителей.
- Определяется необходимость вынесения секции в отдельный топик.
- Определяется имя файла, в котором будет находится секция.
- Исправляются ссылки в документе на содержимое секции с учетом нового имени файла, в котором будет находится секция.

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

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

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

## Подготовка файлов 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-разметки

collection_processing

Для избавления от необходимости прописывать одинаковые фрагменты разметки во многих местах, имеется возможность ее подстановки с помощью элемента 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. Не наследуются элементы:

   - alinks
   - klinks
   - nochilds
   - toc

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

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

subst_processing

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

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

- title
- subst

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

Например:

    <title to="parent"/>

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

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

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

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

См. также|subst_processing

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

process_keywords

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

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

href_processing

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

collection_processing

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

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

См. также|collection_processing

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

## chminfo

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

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

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

## autokw

process_keywords

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

Атрибуты:
  mode

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

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

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

См. также|process_keywords

## alinks

process_keywords

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

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

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

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

См. также|process_keywords

## klinks

process_keywords

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

Атрибуты:
  нет.
Обрабатывается:
  только когда является непосредственным потомком 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

href_processing

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

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

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

См. также|href_processing

## hrefcombine

href_processing

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

Атрибуты:
  нет.
Обрабатывается:
  только когда является непосредственным потомком 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

subst_processing

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

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

subst_processing

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

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

subst_processing

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

Атрибуты:
  to

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

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

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

См. также|subst_processing

## a

subst_processing

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

collection_processing

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

Атрибуты:
  нет.
Обрабатывается:
  только внутри элемента 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

## collection

collection_processing

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

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

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

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

См. также|collection_processing

## file

collection_processing

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

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

См. также|collection_processing