[ Страница назад | Страница вперед | Содержание | Индекс | Библиотека | Юридическая информация | Поиск ]

Программирование: Разработка и отладка программ


Создание индексов документов

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

Требования

Перед созданием индекса убедитесь, что выполнены следующие требования:

Создание индексов

  1. Выбор уникального имени индекса
  2. Создание нового каталога
  3. Создание ASCII-файла
  4. Выбор названия индекса
  5. Создание пустого индекса
  6. Добавление документов в список обновления
  7. Запуск процесса обновления для создания индекса
  8. Обновление таблицы регистрации
  9. Копирование документов HTML в каталог документации
  10. Тестирование индекса
  11. Последний этап

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

Кроме того, при создании пакета installp все документы, относящиеся к одному индексу, должны быть помещены в один устанавливаемый модуль (набор файлов). В противном случае может возникнуть ситуация, когда пользователь установит только часть документов. В результате при попытке открыть найденные документы может появится сообщение об ошибке вида Документ отсутствует.

Для создания индекса нужно выполнить следующие действия:

  1. Выбор уникального имени индекса

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

  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.

  3. Создание ASCII-файла

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

    Если документы расположены так, как было показано выше, в файл 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) была заменена на символ @, так как она была последней косой чертой во временной части пути.

  4. Выбор названия индекса

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

  5. Создание пустого индекса

    Сначала нужно создать пустой индекс. После создания он будет заполнен. Перед созданием индекса проверьте следующее:

    Следующие действия могут выполнять только члены группы imnadm. Перед созданием первого индекса владелец каталога /usr/docsearch/indexes должен быть изменен на imnadm. Это необходимо только для создания первого индекса.

    chown imnadm:imnadm /usr/docsearch/indexes

    Индекс создается в три этапа.

    1. Создайте пустой индекс.

      Для этого нужно выполнить следующую команду:

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

       /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
      
    3. После создания индекса проверьте, что он зарегистрирован в Службе поиска документации в каталоге /usr/IMNSearch/cli/imqixlst.

      /usr/IMNSearch/bin/itelstix -s server

  6. Добавление документов в список обновления

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

    Для добавления файлов в список документов, по которым будет строиться индекс, выполните следующую команду:

    /usr/IMNSearch/bin/itequeue -s server -x индекс -add -l
    файл-списка-документов
    

    (здесь здесь файл-списка-документов - имя файла ASCII со списком документов).

    Примечание: Убедитесь в том, что документы были действительно добавлены в список. Введите:

    /usr/IMNSearch/bin/itestaix -s server -x
    индекс
    

    Число в колонке Количество запросов на индексацию указывает количество документов в индексе.

  7. Запуск процесса обновления для создания индекса

    Запустите процесс обновления индекса. В ходе этого процесса документы из заданного списка будут проиндексированы, а результаты операции будут сохранены в пустом индексе.

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

    Введите следующую команду обновления:

    /usr/IMNSearch/bin/iteupdix -s server -x индекс
    

    Примечание: убедитесь в том, что документы были действительно проиндексированы. Введите:

    /usr/IMNSearch/bin/itestaix -s server -x индекс
    

    Проверьте значение в колонке Количество документов в основном индексе.

  8. Обновление таблицы регистрации

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

    Для обновления таблицы регистрации на компьютере разработчика выполните следующую команду:

    Примечание: после параметра приложение должна быть указана косая черта (/).

    /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>
    
  9. Копирование документов HTML в каталог документации

    Теперь документы в формате HTML можно скопировать в каталог, в котором они будут доступны пользователям. Документы нужно разместить в каталоге /usr/share/man/info/локаль/имя_приложения/имя_индекса. В нашем примере файлы документации по приложению Калькулятор, написанные на английском языке, будут располагаться в каталоге /usr/share/man/info/en_US/calculator/.

    1. Проверьте, существует ли каталог /usr/share/man/info/ локаль. Если каталог не существует, создайте его. При создании предоставьте права на чтение и выполнение для всех пользователей.

      В рассматриваемом примере каталог будет называться /usr/share/man/info/en_US.

    2. Создайте в каталоге языка каталог приложения. Структура каталогов на этом этапе - /usr/share/man/info/локаль/имя_приложения.

      В нашем примере имя каталога приложения - /usr/share/man/info/en_US/calculator.

    3. Скопируйте все документы в каталог приложения. Структура каталогов должна принять следующий вид:

      /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
      
  10. Тестирование индекса

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

  11. Последний этап


[ Страница назад | Страница вперед | Содержание | Индекс | Библиотека | Юридическая информация | Поиск ]