Go to the first, previous, next, last section, table of contents.


Именные указатели

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

Texinfo предоставляет несколько предопределенных видов именных указателей: указатель функций, указатель переменных, указатель понятий и другие. Вы можете объединять именные указатели или использовать их по другому назначению, отличному от обычного. Если вы захотите, вы можете определить свои собственные именные указатели.

Создание вхождений именного указателя

Когда вы создаете вхождения именного указателя, вам стоит помнить о том, что люди могут искать что-то по разному. Разные люди думают о разных словах, когда они что-нибудь ищут. Хороший именной указатель перечисляет вхождения по всем различным словам, которые люди могут использовать для поиска. Например, один читатель может считать очевидным, что двухбуквенные названия именных указателей должны быть перечислены как "Именные указатели, двухбуквенные названия", так как фраза "Именной указатель" -- это общее понятие. Но другой читатель может помнить об особом понятии о двухбуквенных названиях и пытаться найти эту тему как "Двухбуквенные названия именных указателей". Хороший указатель предоставит оба вхождения и поможет обоим читателям.

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

See section Меню-указатели и печать именных указателей, для получения информации о печати именных указателей в конце книги или создании меню-указателей в Info-файле.

Предопределенные именные указатели

Texinfo предоставляет шесть предопределенных именных указателей:

Не в каждом руководстве нужны все шесть, большинство использует два или три из них. В этом руководстве два именных указателя: указатель понятий и указатель @-команд (который на самом деле является указателем функций, но назван в заголовке указателем команд). Два или более указателя могут быть объединены в один при помощи команды @synindex или @syncodeindex. See section Объединение именных указателей.

Определение вхождений именных указателей

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

Вхождение указателя состоит из вносящей это вхождение команды, расположенной в начале строки, за которой на оставшейся части строки следует само вхождение.

Например, этот раздел начинается следующими пятью вхождениями для указателя понятий:

@cindex Добавление вхождений именных указателей
@cindex Вхождения именных указателей
@cindex Именные указатели, вхождения
@cindex Определение вхождений именных указателей
@cindex Создание вхождений именных указателей

Каждый из предопределенных именных указателей имеет свою команду для добавления вхождений; для указателя функций это @findex и так далее.

Вхождения указателя понятий состоят из текста. Наилучшим способом написать именной указатель будет выбирать вхождения короткие, но ясные. Если это возможно, вхождения будут смотрятся лучше, если писать каждое слово с не заглавной буквы, а так, как оно писалось бы в предложении. (Пишите с заглавной буквы имена собственные и аббревиатуры, которые всегда должны писаться заглавными буквами.) Эти соглашения об использовании заглавных букв мы применяем в большинстве именных указателей в руководствах GNU.

Если вам не удается сделать вхождение кратким и при этом ясным, сделайте его более длинным и ясным, а не коротким и непонятным. Если многие вхождения состоят из нескольких слов, именной указатель может смотреться лучше, если вы будете использовать другое соглашение: писать первое слово каждого вхождения с заглавной буквы. Но не пишите с заглавной буквы регистрозависимые названия, такие как имена функций Лиспа или Си или команды оболочки, это может быть синтаксической ошибкой.

Какого бы соглашение об использовании заглавных букв вы не придерживались, пожалуйста, придерживайтесь его постоянно!

Вхождения в других именных указателях, не в указателе понятий, -- это имена символов языков программирования или названия программ; эти названия обычно регистрозависимы, поэтому используйте заглавные и строчные буквы так, как требуется.

По умолчанию вхождения указателя понятий печатаются маленьким романским шрифтом, а вхождения других указателей -- маленьким шрифтом, используемым командой @code. Вы можете изменить вид части вхождения с помощью обычных команд Texinfo, например @file для имен файлов и @emph для обозначения логического ударения (see section Пометка слов и фраз).

Предопределены шесть команд добавления вхождения к именному указателю:

@cindex понятие
Создать вхождение для понятия в указателе понятий.
@findex функция
Создать вхождение для функции в указателе функций.
@vindex переменная
Создать вхождение для переменной в указателе переменных.
@kindex клавиша
Создать вхождение для клавиши в указателе клавиш.
@pindex программа
Создать вхождение для программы в указателе программ.
@tindex тип данных
Создать вхождение для типа данных в указателе типов данных.

Внимание: Не используйте двоеточия в тексте вхождения. В Info двоеточие отделяет название пункта меню от имени ноды, поэтому двоеточие в самом вхождении введет Info в заблуждение. See section Составные части меню, для получения большей информации о структуре пунктов меню.

На самом деле вы не обязаны использовать предопределенные именные указатели по их обычному назначению. Например, предположим, что вы хотите перечислить некоторые макросы препроцессора Си. Вы можете поместить их в указатель функций вместе с настоящими функциями, просто записывая для них команду @findex; затем, при печати "Указателя функций" как ненумерованной главы, вы можете дать ему название "Указатель функций и макросов", и с точки зрения читателя все будет согласовано. Или вы могли бы поместить макросы вместе с типами данных, записывая для них команду @tindex и потом дав этому указателю подходящее название, чтобы читатель вас понял. (See section Меню-указатели и печать именных указателей.)

Объединение именных указателей

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

Вы можете поместить функции в указатель понятий, записывая для них команду @cindex вместо команды @findex, и создать согласованное руководство, напечатав указатель понятий под заголовком `Указатель понятий и функций' и не печатая `Указатель функций' вовсе; но это ненадежный метод. Он работает, только если ваш документ никогда не включается как часть в другой документ, который разрабатывался с отдельным указателем функций; если же вам придется включить его в такой документ, то функции из вашего документа и из другого не будут собраны вместе. Кроме того, чтобы названия функций печатались в указателе понятий правильным шрифтом, вы должны будете заключить каждую из них между фигурными скобками команды @code.

@syncodeindex

Когда вы хотите объединить указатели понятий и функций в один, вы должны перечислять функции с помощью команды @findex, а понятия с помощью команды @cindex, и использовать команду @syncodeindex для перенаправления вхождений указателя функций в указатель понятий.

Команда @syncodeindex принимает два аргумента: название именного указателя, подлежащего перенаправлению, и название указателя, в который он перенаправляется. Шаблон выглядит так:

@syncodeindex источник назначение

Для этой цели именным указателям присвоены двухбуквенные названия:

`cp'
указатель понятий
`fn'
указатель функций
`vr'
указатель переменных
`ky'
указатель клавиш
`pg'
указатель программ
`tp'
указатель типов данных

Пишите команду @syncodeindex до или вскоре после строки end-of-header в начале Texinfo-файла. Например, чтобы объединить указатель функций с указателем понятий, напишите следующее:

@syncodeindex fn cp

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

Для объединения указателей переменных и функций с указателем понятий напишите следующее:

@syncodeindex vr cp
@syncodeindex fn cp

Команда @syncodeindex помещает все вхождения из указателя-`источника' (перенаправляемого именного указателя) напечатанными шрифтом @code, заменяя шрифт, используемый по умолчанию для именного указателя, в который перенаправлены вхождения этого. Таким образом, если вы перенаправили имена функций из указателя функций в указатель понятий, все они будут напечатаны шрифтом @code, как и ожидалось.

@synindex

Команда @synindex делает почти то же самое, что и команда @syncodeindex, но не помещает вхождения из источника со шрифтом @code; вместо него она использует романский шрифт. Таким образом, вы должны использовать @synindex, когда перенаправляете указатель понятий в указатель функций.

See section Меню-указатели и печать именных указателей, для получения информации о печати именного указателя в конце книги или создании меню-указателей в Info-файле.

Определение новых именных указателей

В дополнение к предопределенным именным указателям, вы можете сами определять именные указатели с помощью команд @defindex и @defcodeindex. Эти команды создают новые @-команды для добавления вхождения к именному указателю, которыми вы помечаете вхождения. Команда @defindex используются следующим образом:

@defindex название

Название именного указателя должно быть словом из двух букв, таким как `au'. Например:

@defindex au

Здесь определяется новый именной указатель, называемый `au'. В то же время создается новая команда добавления к указателю, @auindex, которую вы можете использовать для создания вхождений в именной указатель. Новая команда добавления к указателю используется точно так же, как и предопределенные команды.

Например, вот заголовок раздела, за которым следует вхождение указателя понятий и два вхождения указателя `au'.

@section Познавательная семантика
@cindex Схемы кинестетических отображений
@auindex Джонсон, Марк
@auindex Лакоф, Джордж

(Очевидно, в данном примере `au' служит сокращением слова "author" (автор).) Texinfo конструирует новую команду добавления к именному указателю, приписывая к названию указателя строку `index'; таким образом, определение именного указателя `au' приводит к автоматическому созданию команды @auindex.

Для печати именного указателя используйте команду @printindex, как и для предопределенных именных указателей. Например:

@node Author Index, Subject Index, , Top
@unnumbered Авторы

@printindex au

Команда @defcodeindex похожа на @defindex, но печатает вхождения шрифтом @code, а не романским. То есть она создает аналог команды @findex, а не @cindex

Вы должны определять новые именные указатели внутри или сразу после строки Texinfo-файла end-of-header, до любой команды @synindex или @syncodeindex (see section Заголовок Texinfo-файла).


Go to the first, previous, next, last section, table of contents.