                                                         Виктор Форсюк

                       ОПИСАНИЕ ФОРМАТА  .H! ФАЙЛА

                     Данный документ содержит описание формата  файлов,
                     интерпретируемых программой Dan'a Rollins'a HELP и
                     известных в народе как "течхелп".

                     При восстановлении структуры этих файлов автор ис-
                     пользовал только просмотр самих файлов в 16-ричном
                     формате. Ни реассемблирование, ни другой вид реин-
                     жениринга по отношению к программе HELP.EXE by Dan
                     Rollins (C) Flambeaux Software не использовались.

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

                     Разрешается свободное распространение данного опи-
                     сания в немодифицированном виде, а также любое его
                     использование, если при таковом упоминается автор-
                     ство использованной информации.

                     (C)opyright:  Вiктор Форсюк,  1991-1993
                     -------------------------------------------------
                     Дата последнего уточнения структуры:    03/06/92
                     Дата последней редакции текста:         08/03/93



  В структуре H!-файла можно выделить заглавную часть, в которой  сосре-
доточена информация, описывающая базу в целом (название, версия формата,
цвета, таблица строк, заменяемых на короткие токены). Сюда же можно  от-
нести таблицу смещений в файле "страниц" гипертекста - на том основании,
что эта структрура тоже  одна на всю базу.  А вслед за заглавной  частью
идут (подряд друг за  другом) структуры данных, определяющие  "страницы"
или "главы" гипертекста.


I. Структура информации о базе в целом
══════════════════════════════════════

╔═════════════════╗-----------------------------------------------------------
║  Описание базы  ║
╚═════════════════╝
 ■ В начале - текст переменной длины, описывающий содержимое базы, (С) и пр.
   Признак конца этого текста - 1Ah (символ "конец файла")

       ┌───────────────────────────┬────┐
       │ ...произвольный текст...  │ 1A │
       └───────────────────────────┴────┘
                     
                     └─── длина текста не ограничена


╔═════════════════╗-----------------------------------------------------------
║ Версия  формата ║
╚═════════════════╝
 ■ Это поле может содержать одно из трех значений:

   0xFE - устаревший формат  (формат "Help Driver Version 1.2")

   0xFD - формат, который поддерживает "Help Display Driver Version 3.0"
          (в этом формате - база по DOS 3.3)

   0xFC - новый формат: "Help! Display Engine Version 4.02" (и всех 4.xx)
          Этот новый вариант формата далее будет называться форматом
          версии 4.x (по версии интерпретирующих программ).



╔═════════════════╗-----------------------------------------------------------
║  Название базы  ║
╚═════════════════╝
 ■ Строка с названием базы, конец строки - 0 (ASCIZ)

   В самой старой версии (0xFE) это поле отсутствует. Поскольку
   последние версии интерпретирующих программ  Dan'a  Rollins'a
   уже не поддерживают этот устаревший формат - его можно вообще
   исключить из рассмотрения.


╔═════════════════╗-----------------------------------------------------------
║ Атрибуты  цвета ║
╚═════════════════╝
 ■ 20 байт с атрибутами цвета (в основном - несколько байт, очевидно,
   зарезервировно):

   [первые 8 байт относятся к монохромному режиму и по раскладке
    совпадают с приводимой ниже раскладкой следующих 8 байт для
    цветных режимов]

 ───────────────────────────────────────────────────────
   +8   основной текст и рамка
   +9   инвертированные поля (на рамке)
  +10   гиперполе
  +11   активное гиперполе (курсор)
  +12   бордюр экрана
  +13   подсветка #1 ───┐ только начиная
  +14   подсветка #2 ───┘ с версии 4
 ───────────────────────────────────────────────────────
 [остальные байты на цвета не влияют, интерпретация
  этих байт зависит от версии визуализатора]



╔═════════════════════════════════════╗---------------------------------------
║  Таблица часто встречающихся строк  ║
╚═════════════════════════════════════╝
 ■ Формат этой таблицы не зависит от версии. У всех других таблиц
   поле "число элементов таблицы" с версии 4 стало занимать не
   байт, а слово.

   +0   Байт    количество строк в таблице
   +1   ...     строки в ASCIZ (т.е. оканчивающиеся нулем)



╔═════════════════════════════════════════════╗-------------------------------
║  Таблица позиций в файле глав гипертекста   ║
╚═════════════════════════════════════════════╝

   +0   Байт    количество глав в базе - версии до 4
        Слово   то же - версия 4
   ..   ...     Далее следует массив двойных слов (long),
                число его элементов = числу глав
                i-й элемент массива - смещение в файле
                начала i-й главы гипертекста


          На этом заканчивается информация, касающаяся базы в целом.
          Далее идут структуры данных, определяющие главы в базе
          (начала этих структур заданы в таблице позиций).



II. Структура информации о главе
════════════════════════════════

╔══════════════════════════════════╗------------------------------------------
║  Признак присутствия расширений  ║
╚══════════════════════════════════╝

 ■ Это байтовое поле может принимать одно из двух значений:
        0xFF - стандартный формат главы (все версии)
        0xFE - расширенный (только версии 4+)
   Смысл:
        В расширенном формате вслед за этим полем идет таблица
        гиперпереходов, а за ней таблица подсветок ("цветных слов");
        в стандартном - только таблица гиперпереходов, подсветок нет.

╔══════════════════════════╗--------------------------------------------------
║  Таблица гиперпереходов  ║
╚══════════════════════════╝

 ■ Как и у всех таблиц H!-файла, в начале этой таблицы - поле ее
   длины. Размер этого поля: байт - до версии 4, затем - слово.

   +0   байт    (версии до 4)    количество гиперпереходов в главе
   ..   слово   (с версии 4.xx)  то же
   ..   ...     Далее следуют описатели гиперпереходов, в количестве,
                определенном выше.

  Формат описателя гиперперехода:
  ──────────────────────────────────────────────────────────────
  +0    байт    столбец (позиция в строке) начала гиперперехода
  +1    байт    строка в главе, на которой находится гиперполе
  +2    байт    длина поля гиперперехода
  +3    байт    (версии до 4) номер главы - адресата гиперперехода
        слово   (версии 4+)   то же
  ──────────────────────────────────────────────────────────────
  Замечания:

    1.  Два номера глав имеют особый смысл:
                0xFE (0xFFFE) - возврат назад по стеку глав
                0xFF (0xFFFF) - выход из программы
        Поэтому максимальное количество глав в базе версии 3.xx -
        256-2=254 (если не считать экран заставки, глава с # 0,
        то 253). Аналогично для версии 4: 65536-2=65534.

    2. Поскольку под номер строки отводился только один байт, то в
       ранних версиях формата количество строк в главе ограничивалось
       255-ю. С другой стороны, 8 бит под длину поля гиперперехода -
       это слишком много. Поэтому, начиная с версии 4, два старших
       бита из байта длины гиперперехода используются в качестве
       старших бит 10-битного номера строки.

╔══════════════════════════╗--------------------------------------------------
║  Таблица "цветных слов"  ║
╚══════════════════════════╝

   Перед таблицей - байт с количеством элементов в таблице.

  Формат описателя "цветного слова":
  ──────────────────────────────────────────────────────────────
  +0    байт    столбец (позиция в строке) начала подсветки
  +1    слово   строка в главе, на которой находится подсветка
  +3    байт    длина подсвеченного участка
  ──────────────────────────────────────────────────────────────
  При этом, если старший бит последнего поля установлен, то слово
  рисуется цветом #2, иначе - цветом #1.


  За всем этим идет поле с количеством строк на данной странице
  гипертекста. Затем - собственно текст с вкраплениями кодов,
  имеющих следующую интерпретацию:

        00 - это просто признак конца строки

        01 - начало блока : " 01, nn, cc "
                так кодируется последовательность из
                NN символов CC

        02 - начало блока : " 02, SS "
                эти два байта заменяются строкой номер SS
                из словаря

        03 - начало блока : " 03, SS "
                аналогично предыдущему, но после вставленной
                строки добавляется пробел

        04 - начало блока : " 04, SS "
                аналогично 02-блоку, но первый символ
                вставленной строки переводится в верхний
                регистр

        05 - начало блока : " 05, SS "
                объединяет в себе действие двух предыдущих
                кодовых пар

        FF - начало блока : " FF, CC "
                эти два символа заменяются на один символ: CC
                иначе говоря - это просто "экранировка" байтов,
                которые рассматривается как управляющие,
                для того, чтобы просто вставить их коды в текст



                <<< Конец документа >>>

------------------*--------------------------------------*--------------------
Victor Forsyuk    | forth@samsoby.cs.kiev.ua@USSR.EU.net |  Stamp here ;-)
Kiev, Ukraine     | forth@samsoby.cs.kiev.ua (For /USSR) |
------------------*FIDO: 2:463/18.17 *-------------------*--------------------

