Идентификаторы и разделы справки. Построение отображения
Ранее, когда речь шла о создании справочного руководства и работы с ним, не возникала необходимость использования идентификаторов разделов, поскольку в нужном месте открывалась вся справочная система, и поиск раздела осуществлялся с помощью специальных средств - оглавления, указателей и других. Но в ряде случаев, как, например, при получении контекстной справки, необходимо сразу же открывать нужный раздел справочной системы. В этом случае без знания идентификаторов разделов не обойтись. Иногда нужно знать символьный идентификатор, иногда числовой, как, например, при работе с элементами интерфейса формы.
Для того чтобы разделы справочного руководства связать с числовыми и символьными идентификаторами, при работе в HHW требуется установить два отображения. Первое отображение задается в специальной секции MAP, оно устанавливает соответствие между двумя видами идентификаторов. Второе отображение задается в секции ALIAS, - оно связывает символьные идентификаторы с именами файлов, хранящих разделы справки. В совокупности оба отображения позволяют, зная любой из идентификаторов, найти нужный раздел справки.
Поскольку одной из наших целей является включение в справочное руководство специальных контекстных справок, то мы также рассмотрим создание в hhp-проекте секции TEXT POPUPS, в которой задается ссылка на текстовый файл, содержащий контекстные справки и устанавливается соответствие между этими справками и их идентификаторами.
Давайте перейдем к рассмотрению подробностей построения каждого из упомянутых отображений и формирования секций hhp-проекта: MAP, ALIAS, TEXT POPUPS.
Отображение между двумя видами идентификаторов - символьными и числовыми - представляется в виде определения последовательности именованных констант. Синтаксис заимствован из языка С и каждая строка в определении отображения имеет вид:
#define <символьный идентификатор> <числовой идентификатор>
Вот как выглядит отображение, задаваемое для нашего примера:
#define IDH_Man 1000 #define IDH_Wolf 1001 #define IDH_Goat 1002 #define IDH_Cabbage 1003 #define IDH_Boat 1004 #define IDH_River 1005 #define IDH_LeftBank 1006 #define IDH_RightBank 1007 #define IDH_Shark 1008 #define IDH_Island 1009
Ранее, когда речь шла о создании справочного руководства и работы с ним, не возникала необходимость использования идентификаторов разделов, поскольку в нужном месте открывалась вся справочная система, и поиск раздела осуществлялся с помощью специальных средств - оглавления, указателей и других. Но в ряде случаев, как, например, при получении контекстной справки, необходимо сразу же открывать нужный раздел справочной системы. В этом случае без знания идентификаторов разделов не обойтись. Иногда нужно знать символьный идентификатор, иногда числовой, как, например, при работе с элементами интерфейса формы.
Для того чтобы разделы справочного руководства связать с числовыми и символьными идентификаторами, при работе в HHW требуется установить два отображения. Первое отображение задается в специальной секции MAP, оно устанавливает соответствие между двумя видами идентификаторов. Второе отображение задается в секции ALIAS, - оно связывает символьные идентификаторы с именами файлов, хранящих разделы справки. В совокупности оба отображения позволяют, зная любой из идентификаторов, найти нужный раздел справки.
Поскольку одной из наших целей является включение в справочное руководство специальных контекстных справок, то мы также рассмотрим создание в hhp-проекте секции TEXT POPUPS, в которой задается ссылка на текстовый файл, содержащий контекстные справки и устанавливается соответствие между этими справками и их идентификаторами.
Давайте перейдем к рассмотрению подробностей построения каждого из упомянутых отображений и формирования секций hhp-проекта: MAP, ALIAS, TEXT POPUPS.
Отображение между двумя видами идентификаторов - символьными и числовыми - представляется в виде определения последовательности именованных констант. Синтаксис заимствован из языка С и каждая строка в определении отображения имеет вид:
#define <символьный идентификатор> <числовой идентификатор>
Вот как выглядит отображение, задаваемое для нашего примера:
#define IDH_Man 1000 #define IDH_Wolf 1001 #define IDH_Goat 1002 #define IDH_Cabbage 1003 #define IDH_Boat 1004 #define IDH_River 1005 #define IDH_LeftBank 1006 #define IDH_RightBank 1007 #define IDH_Shark 1008 #define IDH_Island 1009
Заметьте, символьные идентификаторы начинаются префиксом IDH_. В этом случае система HHW опознает их как символьные идентификаторы и осуществляет весьма полезные проверки корректности задания отображения между идентификаторами и разделами справки. Так что рекомендуется всегда использовать этот префикс в символьных именах. Это отображение строится в обычном текстовом редакторе внутри HHW, в Блокноте или в Word, если Вы привыкли там работать. Файл сохраняется как текстовый файл с уточнением ".h". Это уточнение типично для заголовочных файлов языка C. По сути, файл таковым и является, он является частью hhp-проекта и хранится в каталоге проекта вместе с остальными файлами. Теперь несколько слов о том, как создается секция MAP.
При работе с вкладкой Project в главном окне среды HHW на левой инструментальной панели расположена специальная кнопка
Щелчок по данной кнопке открывает диалоговое окно, три вкладки которого обеспечивают создание трех секций hhp-проекта, о которых идет речь. Вот как выглядит это окно, открытое на вкладке MAP:
Рис. 9.13. Создание секции MAP
По существу, в этом окне нужно задать имя заголовочного (Header) файла, задающего отображение между символьными и числовыми идентификаторами. Как создается этот файл, я только что рассказал. Казалось бы, нет ничего проще, чем задать имя файла. В данном случае и, к сожалению, это не так. Процесс по непонятным причинам усложнен. При его выполнении возникают ошибочные ситуации, приводящие, по моему мнению, в дальнейшем к некорректной работе системы. Давайте подробно рассмотрим все этапы этого процесса.
Заметьте, символьные идентификаторы начинаются префиксом IDH_. В этом случае система HHW опознает их как символьные идентификаторы и осуществляет весьма полезные проверки корректности задания отображения между идентификаторами и разделами справки. Так что рекомендуется всегда использовать этот префикс в символьных именах. Это отображение строится в обычном текстовом редакторе внутри HHW, в Блокноте или в Word, если Вы привыкли там работать. Файл сохраняется как текстовый файл с уточнением ".h". Это уточнение типично для заголовочных файлов языка C. По сути, файл таковым и является, он является частью hhp-проекта и хранится в каталоге проекта вместе с остальными файлами. Теперь несколько слов о том, как создается секция MAP.
При работе с вкладкой Project в главном окне среды HHW на левой инструментальной панели расположена специальная кнопка
Щелчок по данной кнопке открывает диалоговое окно, три вкладки которого обеспечивают создание трех секций hhp-проекта, о которых идет речь. Вот как выглядит это окно, открытое на вкладке MAP:
Рис. 9.13. Создание секции MAP
По существу, в этом окне нужно задать имя заголовочного (Header) файла, задающего отображение между символьными и числовыми идентификаторами. Как создается этот файл, я только что рассказал. Казалось бы, нет ничего проще, чем задать имя файла. В данном случае и, к сожалению, это не так. Процесс по непонятным причинам усложнен. При его выполнении возникают ошибочные ситуации, приводящие, по моему мнению, в дальнейшем к некорректной работе системы. Давайте подробно рассмотрим все этапы этого процесса.
Рис. 9.14. Первое окно открытия файла
В этом окне уже появилась кнопка Browse. Нажмем ее.
Рис. 9.15. Второе окно открытия файла
Теперь прошу обратить особое внимание на два факта. Первый - в качестве шаблона для поиска файлов указан шаблон "*.h", Второй факт - в открытой папке HelpToWGC не найдено ни одного файла с таким уточнением. Могу Вас заверить, что заголовочные файлы с уточнением h присутствуют в этом каталоге. Прежде чем обсуждать данные факты, продолжим работу. Естественно я ввел известное мне имя заголовочного файла в поле имени и нажал кнопку "Открыть". В результате я получил ответ, что найти файл в каталоге не удалось:
Рис. 9.16. Третье окно открытия файла
После этого мне осталось ничего другого, как вернуться к окну Include File (см. рис. 14) и там попытаться задать имя заголовочного файла. Диалог был продолжен и я получил следующее сообщение:
Рис. 9.17. Четвертое окно открытия файла
После моего утвердительного ответа было сформировано предложение #include, составляющее секцию MAP. Для тех, кто знает язык C, понятно, что предложение #include обрабатывается препроцессором и вставляет заголовочный файл в текст компилируемого модуля. Несмотря на то, что это предложение, в конечном итоге, было сформировано правильно, я понимаю, что система не видит заголовочный файл, а, следовательно, не может построить нужное отображение и в нужный момент открыть требуемый раздел справки
Даже, если бы все работало корректно, то весь этот длинный процесс открытия файла представляется мне примером неудачного, я бы даже сказал, непрофессионального решения.
Несколько слов о том, почему не виден файл с уточнением ".h". Он и не должен быть виден, поскольку это текстовый файл, и он будет отображаться, когда шаблоном будет служить уточнение ".txt". Другое дело, что в грамотной реализации нужно вначале найти все текстовые файлы и отобрать среди них те файлы, которые имеют уточнение h. Подводя итог, следует сказать, что хотя формально секция MAP была создана, но фактически процесс ее создания потерпел неудачу и файл, указанный в этой секции не будет виден системой. Выход из этой ситуации есть, но об этом чуть позже. Аналогичная ситуация с заголовочными файлами возникает и при работе с двумя другими вкладками в процессе создания секций ALIAS и TEXT POPUPS.
Прежде, чем формировать секцию ALIAS, в справочном руководстве HHW рекомендуется построить еще один заголовочный файл, задающий отображение межу символическими идентификаторами и именами файлов, содержащих соответствующие разделы справочного руководства. Я напомню, что алиасом или алиасным именем называется псевдоним, второе имя объекта. В данном случае речь идет о символических идентификаторах, являющихся псевдонимами файлов. Строки заголовочного файла, задающего алиасные имена, имеют следующий синтаксис:
Символьный идентификатор> = <Имя файла>
В нашем примере этот заголовочный файл выглядит следующим образом:
IDH_Man = Man.htm IDH_Wolf = Wolf.htm IDH_Goat = Goat.htm IDH_Cabbage = Cabbage.htm IDH_River = River.htm IDH_LeftBank = LeftBank.htm IDH_RightBank = RightBank.htm IDH_Shark = Shark.htm IDH_Boat = Boat.htm IDH_Island = Island.htm
Перейдем теперь к формированию секции ALIAS. При выборе одноименной вкладки в отличие от вкладки MAP появляются две возможности создания секции.
Рис. 9.18. Создание секции ALIAS
Командная кнопка ADD позволяет создавать секцию ALIAS строку за строкой. Это более долгий и утомительный процесс, в особенности, для больших файлов. Единственное и немаловажное его преимущество состоит в том, что в этом случае удается избежать использования заголовочного файла
Нажатие кнопки INCLUDE позволяет создать секцию ALIAS за один шаг, используя подготовленный в текстовом редакторе заголовочный файл. В этом случае открывается уже знакомое окно "Include File" (рис. 14) и повторяется процесс, так подробно описанный выше.
