Средства поиска документации не выполняют поиск непосредственно в файлах документации. Вместо этого они используют индексы, которые создаются на основе документации. В упрощенном варианте индексы можно представить как сжатые варианты файлов. Индексы значительно увеличивают скорость поиска. В связи с этим перед добавлением документов в службу поиска необходимо создать и установить как минимум один индекс.
Перед созданием индекса убедитесь, что выполнены следующие требования:
Для каждого создаваемого индекса в форме поиска размещается переключатель, позволяющий выбрать соответствующие документы при поиске. Обычно для поиска в группе документов создается единый индекс. При выборе индекса поиск выполняется по всем связанным с ним документам. Следовательно, общий индекс нужно создавать для тематически связанных между собой документов.
Кроме того, при создании пакета installp все документы, относящиеся к одному индексу, должны быть помещены в один устанавливаемый модуль (набор файлов). В противном случае может возникнуть ситуация, когда пользователь установит только часть документов. В результате при попытке открыть найденные документы может появится сообщение об ошибке вида Документ отсутствует.
Для создания индекса нужно выполнить следующие действия:
При создании индекса поиска для документа требуется указать его имя длиной восемь символов. При этом служба поиска не позволяет зарегистрировать индекс, если указанное имя уже зарегистрировано. Для того чтобы сократить число конфликтов имен, при определении имени нового индекса рекомендуется следовать следующим правилам:
Пример: имя указателя для документа на русском языке в кодировке ISO8859-5 должно заканчиваться буквами ru. Примером такого имени может служить 999ak2ru.
Пример: Если приложение называется Calculator, и документ написан на русском языке в кодировке ISO8859-5, имя индекса должно заканчиваться буквами ru. Примером такого имени может служить cal2b4ru.
Язык | Кодовый набор | Локаль | Суффикс
имени индекса | Поддержи-
вается, начиная с версии AIX: |
---|---|---|---|---|
Каталанский | ISO8859-1 | ca_ES | имя ca | 4.3.0 |
ISO8859-15 | ca _ES.8859-15 | имя c5 | 4.3.2 | |
Датский | ISO8859-1 | da_DK | имя da | 4.3.0 |
Голландский (Нидерланды) | ISO8859-1 | nl_NL | имя nl | 4.3.0 |
ISO8859-15 | nl_NL.8859-15 | имя b5 | 4.3.2 | |
Английский (США) | ISO8859-1 | en_US | имя en | 4.3.0 |
ISO8859-1 | C | имя en | 4.3.0 | |
Английский (Великобритания) | ISO8859-1 | en_GB | имя gb | 4.3.0 |
Финский | ISO8859-1 | fi_FI | имя fi | 4.3.0 |
ISO8859-15 | fi_FI.8859-15 | имя u5 | 4.3.2 | |
Французский | ISO8859-1 | fr_FR | имя fr | 4.3.0 |
ISO8859-15 | fr_FR.8859-15 | имя f5 | 4.3.2 | |
Французский (Канада) | ISO8859-1 | fr_CA | имя fc | 4.3.0 |
Немецкий | ISO8859-1 | de_DE | имя de | 4.3.0 |
ISO8859-15 | de_DE.8859-15 | имя d5 | 4.3.2 | |
Немецкий (Швейцария) | ISO8859-1 | de_CH | имя cd | 4.3.0 |
Исландский | ISO8859-1 | is_IS | имя is | 4.3.0 |
Итальянский | ISO8859-1 | it_IT | имя it | 4.3.0 |
ISO8859-15 | it_IT.8859-15 | имя i5 | 4.3.2 | |
Норвежский | ISO8859-1 | no_NO | имя no | 4.3.0 |
Португальский (Бразилия) | ISO8859-1 | pt_BR | имя pt | 4.3.0 |
Португальский (Португалия) | ISO8859-1 | pt_PT | имя po | 4.3.0 |
ISO8859-15 | pt_PT.8859-15 | имя y5 | 4.3.2 | |
Русский | ISO8859-5 | ru_RU | имя ru | 5.0.0 |
Испанский | ISO8859-1 | es_ES | имя es | 4.3.0 |
ISO8859-15 | es_ES.8859-15 | name s5 | 4.3.2 | |
Шведский | ISO8859-1 | sv_SE | имя sv | 4.3.0 |
Японский | IBM-932 | Ja_JP | имя jp | 4.3.2 |
Корейский | IBM-eucKR | ko_KR | имя kr | 4.3.2 |
Упрощенный китайский | IBM-eucCN | zh_CN | имя cn | 4.3.2 |
Традиционный китайский | big5 | Zh_TW | имя tw | 4.3.2 |
Создайте каталог для хранения документов, которые будут включены в индекс. Мы будем называть его рабочим каталогом. Он может располагаться в любом месте. В нашем примере при создании индексов для документации приложения "Калькулятор" будет использоваться каталог /usr/work/calculator. Внутри рабочего каталога документы должны располагаться в виде структуры, которая будет использоваться для их хранения на сервере документации.
В результате полный путь к каждому документу будет состоять из постоянной и временной части. Временная часть пути - это путь к рабочему каталогу. Постоянная часть определяет положение документа в дереве документов. После создания индекса постоянную часть пути изменить уже нельзя. Одним из правил формирования имен является то, что первым каталогом в постоянном пути должен быть каталог, имя которого совпадает с именем индекса.
Предположим, например, что приложение называется calculator. Электронная документация к приложению написана на Английском (США). Документация состоит из двух руководств пользователя (doc1, doc2) и одного документа по администрированию (doc3). В файловой системе компьютера, на котором будет создаваться индекс, эти документы могут быть расположены следующим образом:
/usr/work/calculator/user/doc1.html /usr/work/calculator/user/doc2.html /usr/work/calculator/admin/doc3.html
Рабочий каталог может находиться в произвольном месте, но все документы, которые будут упоминаться в указателе, должны находиться в одном каталоге, который будет играть роль корневого каталога для дерева документов. В данном примере корневым будет каталог calculator.
Для каждого индекса необходимо создать файл со списком документов. В этом списке должны присутствовать все документы, входящие в индекс. Для каждого документа необходимо указать полное имя. Обратите внимание, что расположение документов на рабочем компьютере не обязательно должно совпадать с их будущим расположением на сервере документации. Имя файла со списком документов может быть любым. Он может располагаться в любом каталоге. Каждый путь к документу должен быть расположен в отдельной строке файла.
Если документы расположены так, как было показано выше, в файл ASCII должны быть записаны следующие пути:
/usr/work/calculator/user/doc1.html /usr/work/calculator/user/doc2.html /usr/work/calculator/admin/doc3.html
В файле нужно указать, где заканчивается временная часть пути и начинается постоянная часть. Для этого последнюю косую черту (/) временного пути (пути к рабочему каталогу) необходимо заменить на символ коммерческого "at" (@). При создании индекса будет сохранена только та часть пути, которая расположена справа от символа @.
Например, указанные выше пути будут преобразованы следующим образом:
/usr/work@calculator/user/doc1.html /usr/work@calculator/user/doc2.html /usr/work@calculator/admin/doc3.html
Косая черта перед именем приложения (calculator) была заменена на символ @, так как она была последней косой чертой во временной части пути.
Название индекса - это текст, который будет выводиться рядом с переключателем в форме поиска. Название должно описывать документы, входящие в состав индекса, и содержать не более 150 символов.
Сначала нужно создать пустой индекс. После создания он будет заполнен. Перед созданием индекса проверьте следующее:
Следующие действия могут выполнять только члены группы imnadm. Перед созданием первого индекса владелец каталога /usr/docsearch/indexes должен быть изменен на imnadm. Это необходимо только для создания первого индекса.
chown imnadm:imnadm /usr/docsearch/indexes
Индекс создается в три этапа.
Для этого нужно выполнить следующую команду:
/usr/IMNSearch/bin/itecrix -s server -x индекс -p /usr/docsearch/indexes/индекс/data -pw /usr/docsearch/indexes/индекс/work -lsse itelsswt -t NORM | -t NGRAM -ccsid <ИД-кодового-набора>
Здесь индекс - это имя создаваемого индекса длиной 8
символов. Значения флагов -t и -ccsid зависят от языка, на котором
написаны документы. Для всех однобайтовых языков флагу -t должно быть
присвоено значение NORM. Для всех многобайтовых языков флагу -t должно
быть присвоено значение NGRAM, а для создания индексов на таких языках нужно
указать соответствующее значение -ccsid. В следующей таблице приведены
значения флагов для различных языков:
Язык | -t | -ccsid | -lang |
Английский (США) ISO8859-1 | NORM | 819 | EN_US |
Английский (США) ISO8859-15 | NORM | 923 | EN_US |
Английский (Великобритания) ISO8859-1 | NORM | 819 | EN_GB |
Каталанский ISO8859-1 | NORM | 819 | CA_ES |
Каталанский ISO8859-15 | NORM | 923 | CA_ES |
Французский ISO8859-1 | NORM | 819 | FR_FR |
Французский ISO8859-15 | NORM | 923 | FR_FR |
Французский (Канада) ISO8859-1 | NORM | 819 | FR_FR |
Немецкий ISO8859-1 | NORM | 819 | DE_DE |
Немецкий ISO8859-15 | NORM | 923 | DE_DE |
Немецкий (Швейцария) ISO8859-1 | NORM | 819 | DE_CH |
Исландский ISO8859-1 | NORM | 819 | IS_IS |
Итальянский ISO8859-1 | NORM | 819 | IT_IT |
Итальянский ISO8859-15 | NORM | 923 | IT_IT |
Норвежский ISO8859-1 | NORM | 819 | NO_NO |
Португальский (Бразилия) ISO8859-1 | NORM | 819 | PT_BR |
Португальский (Португалия) ISO8859-1 | NORM | 819 | PT_PT |
Португальский (Португалия) ISO8859-15 | NORM | 923 | PT_PT |
Русский ISO8859-9 | NORM | 878 | RU_RU |
Испанский ISO8859-1 | NORM | 819 | ES_ES |
Испанский ISO8859-15 | NORM | 923 | ES_ES |
Шведский ISO8859-1 | NORM | 819 | SV_SE |
Японский IBM-932 | NGRAM | 932 | JA_JP |
Корейский IBM-eucKR | NGRAM | 949 | KO_KR |
Традиционный китайский big5 | NGRAM | 950 | ZH_TW |
Упрощенный китайский IBM-eucCN | NGRAM | 1381 | ZH_CN |
Например, для создания индекса на английском языке нужно выполнить следующую команду:
/usr/IMNSearch/bin/itecrix -s server -x cal413en -p /usr/docsearch/indexes/cal413en/data -pw /usr/docsearch/indexes/cal413en/work -lsse itelsswt -t NORM
/usr/IMNSearch/bin/iterulix -s server -x индекс -dfmt HTML -ccsid <кодовый-набор -lang <язык
Здесь индекс - имя индекса, созданного предыдущей командой, а кодовый-набор и язык - значения из таблицы, приведенной выше.
В нашем примере это будет такая команда:
/usr/IMNSearch/bin/iterulix -s server -x cal413en -dfmt HTML -ccsid 819 -lang EN_US
/usr/IMNSearch/bin/itelstix -s server
Теперь нужно задать для Службы поиска документации имя файла, хранящего список документов, которые будут включены в созданный индекс. После этого вы сможете запустить команду обновления и эти документы будут проиндексированы, а результаты операции будут добавлены в индекс.
Для добавления файлов в список документов, по которым будет строиться индекс, выполните следующую команду:
/usr/IMNSearch/bin/itequeue -s server -x индекс -add -l файл-списка-документов
(здесь здесь файл-списка-документов - имя файла ASCII со списком документов).
Примечание: Убедитесь в том, что документы были действительно добавлены в список. Введите:
/usr/IMNSearch/bin/itestaix -s server -x индекс
Число в колонке Количество запросов на индексацию указывает количество документов в индексе.
Запустите процесс обновления индекса. В ходе этого процесса документы из заданного списка будут проиндексированы, а результаты операции будут сохранены в пустом индексе.
Примечание: создание индексов - это длительный процесс. Невозможно перейти к этапу Обновление таблицы регистрации до завершения индексации. Для того чтобы узнать, завершено ли создание индекса, введите указанную ниже команду.
Введите следующую команду обновления:
/usr/IMNSearch/bin/iteupdix -s server -x индекс
Примечание: убедитесь в том, что документы были действительно проиндексированы. Введите:
/usr/IMNSearch/bin/itestaix -s server -x индекс
Проверьте значение в колонке Количество документов в основном индексе.
После этого нужно добавить индекс в таблицу регистрации компьютера разработчика, чтобы его можно было протестировать в службе поиска документации.
Для обновления таблицы регистрации на компьютере разработчика выполните следующую команду:
Примечание: после параметра приложение должна быть указана косая черта (/).
/usr/IMNSearch/bin/itedomap -p /var/docsearch/indexes -c -x индекс -sp /doc_link/локаль/приложение/ -ti заголовок-индекса
Переменная локаль - это имя языкового каталога, расположенного в /usr/share/man/info и хранящего документы индекса. Переменная индекс задает имя индекса, а заголовок-индекса - название, которое будет показано в форме поиска. Заголовок выводится в нижней части формы поиска, предназначенной для выбора индекса. Помните, что название должно быть написано на том же языке, что и документы, относящиеся к индексу.
Кроме этого, рекомендуется указывать названия в виде ссылок HTML. В
этом случае они будут показаны в форме поиска как ссылки на соответствующие
документы. Это позволит пользователям открывать первый документ
индекса, щелкнув по соответствующей ссылке.
Примечание:
у каждого Web-сервера есть внутренний домашний каталог, с которого он начинает поиск документов. После установки и настройки Службы поиска документации в файловой системе создается ссылка на этот каталог. Эта ссылка указывает на стандартный каталог хранения документов в AIX: /usr/share/man/info. Так как сервер автоматически ищет документы в этом каталоге, механизму поиска необходимо сообщить только о части пути к документу, относительно этого расположения. Служба поиска документации создает в начальном каталоге Web-сервера следующую ссылку: doc_link -> /usr/share/man/info После этого Web-сервер может обрабатывать запросы к документам следующего типа: http://your.machine.name/doc_link/en_US/calculator/user/doc1.html |
Допустим, вы хотите озаглавить индекс как Руководства по приложению Калькулятор. Индекс с именем cal413en создан по трем документам (руководствам). Предположим, что при щелчке на названии индекса должно открываться Руководство для начинающих. Для этого в название нужно добавить ссылку на это руководство. Если этот документ располагается по адресу /doc_link/en_US/calculator/user/doc1.htm (doc_link - это ссылка на каталог /usr/share/man/info), то для вызова Руководства для начинающих по ссылке индекса нужно выполнить следующую команду:
/usr/IMNSearch/bin/itedomap -p /var/docsearch/indexes -c -x cal413en -sp /doc_link/en_US/calculator/ -ti <A HREF='/doc_link/en_US/calculator/user/doc1.htm'>Руководства по работе с калькулятором</A>
Теперь документы в формате HTML можно скопировать в каталог, в котором они будут доступны пользователям. Документы нужно разместить в каталоге /usr/share/man/info/локаль/имя_приложения/имя_индекса. В нашем примере файлы документации по приложению Калькулятор, написанные на английском языке, будут располагаться в каталоге /usr/share/man/info/en_US/calculator/.
В рассматриваемом примере каталог будет называться /usr/share/man/info/en_US.
В нашем примере имя каталога приложения - /usr/share/man/info/en_US/calculator.
/usr/share/man/info/локаль/приложение/документы.
Для копирования документации программы Калькулятор нужно выполнить следующую команду:
cp -R /usr/work/calculator/* /usr/share/man/info/en_US/calculator
Ниже описано окончательное расположение документации к приложению:
/usr/share/man/info/en_US/calculator/user/doc1.html /usr/share/man/info/en_US/calculator/user/doc2.html /usr/share/man/info/en_US/calculator/admin/doc3.html
Создание и регистрация индекса на компьютере разработчика закончена. Теперь нужно протестировать индекс, открыв форму поиска и введя ключевые слова, которые заведомо присутствуют в документах индекса. Если индекс работает неправильно, его требуется удалить и создать повторно. Для этого перейдите к разделу Удаление индексов документации (Удаление индексов документов). Если индекс работает правильно, перейдите к следующему этапу:
cd /usr/docsearch/indexes
tar cvf индекс.tar индекс
Примечание: Файл tar нужно передать в двоичном режиме.
cd /usr/docsearch/indexes
tar xvf индекс.tar
chown -R imnadm:imnadm индекс
/usr/IMNSearch/bin/itess -stop search
Введите следующую команду:
/usr/IMNSearch/bin/itemtupd -m /etc/IMNSearch -i /usr/docsearch/indexes/индекс/data -w /usr/docsearch/indexes/индекс/work -n индекс
/usr/IMNSearch/bin/itess -start search
Для обновления таблицы регистрации на компьютере разработчика выполните следующую команду:
Примечание: в следующей команде после параметра приложение необходимо указать косую черту (/).
/usr/IMNSearch/bin/itedomap -p /var/docsearch/indexes -c -x индекс -sp /doc_link/locale/приложение/ -ti заголовок-индекса
Переменная локаль - это имя языкового каталога, расположенного в /usr/share/man/info и хранящего документы индекса. Переменная имя_индекса задает имя индекса, а название_индекса - название, которое будет показано в форме поиска. Заголовок выводится в нижней части формы поиска, предназначенной для выбора индекса. Помните, что название должно быть написано на том же языке, что и документы, относящиеся к индексу.
Кроме этого, рекомендуется указывать названия в виде ссылок HTML. В этом случае они будут показаны в форме поиска как ссылки на соответствующие документы. Это позволит пользователям открывать первый документ индекса, щелкнув по соответствующей ссылке.
Предположим, что вы решили назвать индекс Руководства по приложению Калькулятор. Индекс с именем cal413en создан по трем документам (руководствам). Предположим, что при щелчке на названии индекса должно открываться Руководство для начинающих. Для этого в название нужно добавить ссылку на это руководство. Если этот документ располагается по адресу /doc_link/en_US/calculator/user/doc1.htm (doc_link - это ссылка на каталог /usr/share/man/info), то для вызова Руководства для начинающих по ссылке индекса нужно выполнить следующую команду:
/usr/IMNSearch/bin/itedomap -p /var/docsearch/indexes -c -x cal413en -sp /doc_link/en_US/calculator/ -ti <A HREF='/doc_link/en_US/calculator/user/doc1.htm'>Руководства по работе с калькулятором</A>