Существует два способа просмотра документации:
Для того чтобы пользователи могли просматривать документы из глобального набора библиотек, требуется выполнить следующие действия:
Примечание: Вы можете зарегистрировать документы в любой другой библиотеке из стандартного набора. Для этого нужно выполнить те же действия, что и для библиотеки Books, хотя может потребоваться создание файла определений для каждой библиотеки.
Если документация написана на английском, ссылка может иметь следующий вид:
<A HREF="/cgi-bin/ds_form?lang=en_US">Home/Search</A>
Для того чтобы пользователи могли просматривать документы, относящиеся только к конкретному приложению, необходимо создать настраиваемый набор библиотек.
Пример: Если набор библиотек называется MyDocuments и документы написаны на английском языке, файл настройки должен располагаться в каталоге /usr/docsearch/views/en_US/MyDocuments/config
Примечание: Строки файла настройки, начинающиеся с символа #, считаются комментариями и игнорируются.
В файле настройки набора библиотек могут быть заданы следующие
параметры:
| Поле | Описание и примеры |
|---|---|
| Имя и метка библиотеки | Имя набора и метка, которая будет показана на закладке библиотеки
документов. Необходимо как имя, так и метка библиотеки, поскольку метки
идентифицируют версии библиотеки на различных языках. Например, вы
можете использовать в своих документах ссылку на библиотеку документов
Books, при этом Books будет указывать имя библиотеки, а
метка Libros будет указывать на испанскую версию документов.
view = имя-библиотеки <TAB> метка библиотеки Пример: Если библиотека называется Задачи, и вы хотите, чтобы метка называлась Каким образом..., добавьте в файл настройки следующую строку:
view = Задачи Каким образом... |
| title | Текст, который будет выводиться в верхней части окна библиотеки или
браузера.
title=Название библиотеки Пример: Если вы хотите использовать в качестве заголовка окна библиотеки текст Моя документация, добавьте в файл настройки библиотеки документов следующий текст:
title = Моя документация |
| results_title | Текст, который будет выводиться в верхней части окна результатов.
results_title=Название окна результатов Пример: Если вы хотите использовать в качестве заголовка окна результатов текст Результаты поиска моей документации, добавьте в файл настройки библиотеки документов следующий текст:
results_title = Результаты поиска в моей документации |
| page_top | Заменяет стандартный заголовок библиотеки текстом HTML, который
расположен между тегами page_top_begin и
page_top_end.
Пример: Если вы хотите добавить в заголовок страницы изображение, расположенное в файле myimage.gif из каталога /myimages Web-сервера, и изменить название формы на Мои документы, добавьте следующие строки в файл настройки:
page_top_begin <HTML> <HEAD> <TITLE>Мои документы</TITLE> <BODY> <DIV ALIGN="CENTER"> <IMG SRC="/myimages/myimage.gif"> </DIV> <P> page_top_end Примечание : Строка title файла настройки будет проигнорирована. |
| page_bottom | Заменяет стандартный нижний колонтитул страниц библиотеки текстом HTML,
который расположен между тегами page_bottom_begin и
page_bottom_end.
Пример: Если вы хотите, чтобы в нижней части страницы присутствовала ссылка MAILTO, которая позволит пользователям отправлять сообщения администратору, добавьте в файл настройки следующий текст:
page_bottom_begin <HR> <DIV ALIGN="CENTER"> <A HREF="MAILTO:me@my.site">Отзывы</A> </DIV> </BODY> </HTML> page_bottom_end |
| results_top | Заменяет верхний колонтитул страницы результатов, используемый по
умолчанию, на текст, расположенный между тегами results_top_begin и
results_top_end.
Пример: Если вы хотите добавить в заголовок страницы изображение, расположенное в файле myimage.gif из каталога /myimages Web-сервера, и изменить название формы на Результаты поиска, добавьте следующие строки в файл настройки:
results_top_begin <HTML> <HEAD> <TITLE>Результаты поиска</TITLE> <BODY> <DIV ALIGN="CENTER"> <IMG SRC="/myimages/myimage.gif"> </DIV> results_top_end Примечание: запись results_title файла настройки будет проигнорирована. |
| results_bottom | Заменяет нижний колонтитул страницы результатов, используемый по
умолчанию, на текст, расположенный между тегами
results_bottom_begin и results_bottom_end.
Пример: Если вы хотите, чтобы в нижней части страницы результатов присутствовала ссылка MAILTO, которая позволит пользователям отправлять сообщения администратору, добавьте в файл настройки следующий текст:
results_bottom_begin <HR> <DIV ALIGN="CENTER"> <A HREF="MAILTO:me@my.site">Отзывы</A> </DIV> </BODY> </HTML> results_bottom_end |
Создайте файл определения для каждой библиотеки из набора. Записи в файле должны быть заданы в следующем формате:
#<TAB>Заголовок записи[<TAB>Поле:значение...] #<TAB>Заголовок записи[<TAB>Поле:значение...] #<TAB>Заголовок записи[<TAB>Поле:значение...]
Символом # обозначен уровень записи в иерархической структуре,
название - это текст, который будет показан в библиотеке, а поле - одно из
полей, перечисленных ниже. Первый уровень записей всегда
равняется 0 и может изменяться до 9 по мере роста глубины вложенности.
Записи с одинаковым уровнем выводятся с одинаковым выравниванием по левому
краю. (Уровень записи можно воспринимать как число табуляций перед
текстом названия).
| Поле | Описание и примеры |
|---|---|
| Printfile | Начиная с версии 5.1, в AIX поддерживается этот тег VDF. С
помощью этого тега можно создать ссылку на книгу в списке книг, которые можно
напечатать. Если пользователь щелкнет на ссылке в окне Средство печати,
то в браузер пользователя будет загружена вся книга в формате, предназначенном
для печати. Поэтому прежде чем указывать данный тег в файле VDF, нужно
создать файл книги в формате для печати. Дополнительная информация об
этом приведена в разделе Печать документации.
Тег Printfile должен быть указан в следующем формате: Printfile[1-20]:/doc_link/$path Указанная ссылка будет добавлена в список книг, которые можно напечатать. $path - это путь к файлу в формате для печати. Файл должен находиться в пределах дерева каталогов /usr/share/man/info. Ссылка doc_link автоматически указывает на каталог документов web-сервера службы документации. Обычно она указывает на /usr/share/man/info, и поэтому ваш файл тоже должен находиться в /usr/share/man/info. Номер (1-20) указывать не обязательно. Он предназначен для случаев, когда книга слишком большая для размещения в одном файле. Тогда ее можно разбить на несколько файлов, общим числом не более 20. В этом случае номер указывает номер раздела книги. Для каждого раздела книги в списке книг для печати будет создана отдельная ссылка. Если же книга состоит только из одного файла, номер указывать не нужно. Примеры: предположим, что ваша программа называется Esther, а руководство по программе в формате для печати - userguide.pdf: Если руководство поставляется в одном файле и только на одном языке (на английском), то нужно указать следующий тег: Printfile:/doc_link/esther/userguide.pdf Если книга в формате для печати будет разбита на две части, то следует указать следующий тег: Printfile1:/doc_link/esther/userguide_section1.pdf Printfile2:/doc_link/esther/userguide_section2.pdf Допустим, что вы поставляете руководство на английском и испанском языках. Тогда нужно указать отдельные теги для английской и испанской версии: Printfile:/doc_link/english/esther/myownbigbook/userguide.pdf Printfile:/doc_link/spanish/esther/myownbigbook/userguide.pdf |
| Checked | Указывает, будет ли элемент отмечен для поиска по умолчанию.
(Параметр может быть указан только для настраиваемых библиотек
документов.) Возможные значения: Yes и
No. Если поле Checked отсутствует, используется
значение по умолчанию (отмечено, т.е. Yes).
Примеры:Checked: Yes
Checked: No
|
| Collate | Задает режим сортировки дочерних элементов данного элемента
(т.е. будут ли они выведены в исходном порядке или отсортированы
по алфавиту в соответствии с локалью). Возможные значения:
Yes и No. Если поле Collate не задано,
используется значение по умолчанию (не сортировать, т.е.
No).
Примеры:Collate: Yes
Collate: No
|
| Expand | Указывает, будет ли этот узел дерева развернут или свернут по
умолчанию. (Параметр может быть указан только для настраиваемых
библиотек документов.) Возможные значения: Yes и
No. Если поле Expand не задано, используется
значение по умолчанию (свернут, т.е. No).
Примеры:Expand: Yes
Expand: No
|
| Extra | Задает текст, который будет показан после названия, вне ссылки
HTML.
Пример: Extra: Текст, не входящий в ссылку. |
| Icon | Задает имя файла, в котором расположен значок, выводимый слева от
названия.
Ниже приведен список стандартных значков службы поиска документации:
Эти значки расположены в каталоге /usr/docsearch/images.
Если вы хотите использовать другой значок, поместите его в этот каталог
сервера документации. Если поле Icon не задано, значок не
выводится.
Примечание: Значки имеют стандартный размер 24х24 пиксела. Если вы укажете значок другого размера, он будет преобразован в рисунок размера 24х24. |
| Index | Задает имена индексов службы поиска для документов этого элемента и его
дочерних элементов. Для того чтобы указать несколько индексов,
перечислите их, разделив запятыми. После того как в файле определений
будут заданы индексы для элемента, для него не могут быть добавлены другие
индексы в других файлах определений. Это гарантирует, что часть дерева
ниже данного элемента в точности соответствует набору проиндексированных
документов.
Примеры: Index:BSADMNEN
Index: CMDS01EN,CMDS02EN,CMDS03EN, CMDS04EN,CMDS05EN,CMDS06EN
|
| Position | Задает желательное относительное положение внутри контейнера.
Например, если вы добавляете статью в книгу и хотите, чтобы ее название было
третьим пунктом оглавления, вы можете задать для нее позицию номер
3, если статьи с позициями 1 и 2 уже
определены. Если задано несколько элементов с одинаковым номером
позиции, их порядок будет определяться значением поля Collate родительской записи. Позиция
записи в файле определения библиотеки имеет более высокий приоритет, чем поле
позиции. Поэтому нет необходимости указывать это поле для записей,
расположенных ниже точки, в которой то же место может быть занято другими
книгами. Если поле Position не задано, по умолчанию
используется нулевая позиция (0).
Пример: Position:5 |
| URL | Адрес документа, к которому следует перейти по ссылке. Это поле
применяется для поиска документа при работе через Web-сервер. В
качестве адреса необходимо ввести полный путь без указания протокола
(http://) и порта сервера. Если поле URL не задано, запись не
будет показана как ссылка HTML.
Пример:URL:/doc_link/en_US/a_doc_lib/cmds/aixcmds2/grep.htm |
| версия | Версия данного элемента. При регистрации документации записи с
большим номером версии заменят записи с меньшем номером.
Пример: Version:4.3.2.0 |
Ниже приведен пример части файла определения библиотеки документации:
0 AIX Base Library Position:1 Icon:library.gif
1 AIX System Management Guides Position:1 Icon:bookshelf.gif
2 Operating System and Devices Index:BADMNEN Postion:1
Icon:book.gif
3 Глава 1. System Management with AIX URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/Ch1.htm
Icon:chapter.gif
4 The System Administrator's Objectives URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/Ch1.htm#CE13340208vick
Icon:paper.gif
3 Глава 2. Starting and Stopping the System URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/Ch2.htm
Icon:chapter.gif
4 Starting the System URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/starting.htm
Icon:paper.gif
4 Understanding the Boot Process URL:/doc_link/en_US/a_doc_lib/aixbman/baseadmn/under_boot.htm Icon:paper.gif
.
.
.
/usr/sbin/ds_reg [-d] локаль набор-библиотек библиотека файл-определения
Здесь значение локаль соответствует локали (языку) документов, набор_библиотек - имени набора библиотек, библиотека - имени библиотеки, в которой вы хотите зарегистрировать свою документацию, а файл_определения_библиотеки - имени файла определения библиотеки. Для удаления данных регистрации файла определения нужно выполнить ту же команду с флагом -d.
Пример: Для регистрации файла определения /MyDocuments/Books.vdf в библиотеке Global Books на английском языке введите:
/usr/sbin/ds_reg en_US Global Books /MyDocuments/Books.vdf
Пример: Для удаления данных о регистрации файла определения /MyDocuments/Commands.vdf из библиотеки документации по AIX на испанском языке введите:
/usr/sbin/ds_reg -d es_ES AIX Commands /MyDocuments/Commands.vdf
Основной ссылкой программы CGI Службы поиска документации является
/cgi-bin/ds_form. Этот адрес может быть дополнен одним из
перечисленных ниже аргументов. Аргумент отделяются амперсандами
(&).
| Аргумент | Описание и пример |
|---|---|
| lang | Локаль документации. Если локаль не задана, используется
стандартная локаль сервера документации.
Пример: Для просмотра документации на японском языке укажите следующую ссылку:
<A HREF="/cgi-bin/ds_form?lang=ru_RU"> |
| viewset | Имя набора библиотек. Если имя не задано, будет использоваться
стандартный набор.
Пример: Для просмотра набора библиотек MyDocuments укажите ссылку:
<A HREF="/cgi-bin/ds_form?viewset=MyDocuments"> |
| view | Библиотека документов. Если библиотека не задана, используется
первая библиотека набора.
Пример: Если вам требуется просмотреть библиотеку Commands из стандартного набора библиотек, добавьте следующую ссылку:
<A HREF="/cgi-bin/ds_form?view=Commands"> |
| advanced | Указывает, что должна быть показана расширенная форма поиска. Если
аргумент не указан, выводится простая форма поиска.
Пример: Для вывода расширенной формы поиска используйте ссылку:
<A HREF="/cgi-bin/ds_form?advanced"> |
Пример: Если вы хотите создать ссылку для испанской (es_ES) версии документации, зарегистрированной как библиотека Subroutines в настраиваемом наборе MyDocuments, вы можете указать следующую ссылку:
<A HREF="/cgi-bin/ds_form?viewset=MyDocuments&view=Subroutines&lang=es_ES">