Пометка слов и фраз

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

Обозначение определений, команд, etc.

В Texinfo есть команды для обозначения того, на какой именно вид объектов ссылается фрагмент текста. Например, метасинтаксические переменные помечаются командой @var, а программный код --- командой @code. Так как фрагменты текста помечаются командами, говорящими, объектами какого сорта они являются, легко изменить способ обработки такого текста программами форматирования Texinfo. (Texinfo --- язык смысловой разметки, а не верстки.)

Например, в печатном руководстве программный код показывается равноширинным шрифтом; @code велит TeX набирать данный текст этим шрифтом. Но можно было бы легко поменять способ, которым TeX выделяет код, так, чтобы использовался другой шрифт, и это изменение не затронет способ выделения примеров пользовательского ввода с клавиатуры. Если бы в теле файла использовались непосредственные команды набора, и вы решили сделать такое изменение, вам пришлось бы проверить каждое вхождение, чтобы убедиться, что вы меняете вид кода, а не чего-то другого, что не должно меняться.

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

Эти команды служат для множества целей:

@code{пример-кода}

Обозначает текст, являющийся примером или фрагментом программы.

@kbd{символы-клавиатуры}

Обозначает текст, вводимый с клавиатуры.

@key{название-клавиши}

Обозначает обычно используемое название клавиши на клавиатуре.

@samp{текст}

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

@var{метасинтаксическая-переменная}

Обозначает метасинтаксическую переменную.

@env{переменная-среды}

Обозначает имя переменной среды.

@file{имя-файла}

Обозначает имя файла.

@command{команда}

Обозначает текст, являющийся именем команды оболочки.

@option{ключ}

Обозначает ключ командной строки для какой-то программы.

@dfn{термин}

Обозначает вводимый или определяемый термин.

@cite{ссылка}

Обозначает название книги.

@acronym{аббревиатура}

Обозначает аббревиатуру.

@url{унифицированный-указатель-ресурса}

Обозначает унифицированный указатель ресурса в World Wide Web.

@email{почтовый-адрес[, отображаемый-текст]}

Обозначает адрес электронной почты.

@code{пример-кода}

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

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

Используйте @code для имен команд командных языков, похожих на языки программирования, таких как Texinfo. Например, @code и @samp записаны в исходном Texinfo-файле как `@code{@@code}' и `@code{@@samp}', соответственно.

Менять регистр слова внутри команды @code, когда оно стоит в начале предложения, неправильно. Большинство компьютерных языков регистрозависимы. В Си, например, Printf отличается от идентификатора printf и, скорее всего, является его неправильной записью. Даже в языках, не учитывающих регистр букв, пользователя смутит различное написание идентификаторов. Выберите одно написание и придерживайтесь его всегда. Если вы не хотите начинать предложение с имени команды, написанного строчными буквами, вам нужно перестроить предложение.

В печатном руководстве @code заставляет TeX набирать аргумент в стиле печатной машинки (равноширинным шрифтом). В Info-файле, она велит командам форматирования для Info окружать текст одиночными кавычками.

Например,

Используйте @code{ediff-files} для сравнения двух файлов.

дает в печатном руководстве следующее:

Используйте ediff-files для сравнения двух файлов.

и такое в Info-файле:

Используйте `ediff-files' для сравнения двух файлов.

Вот несколько случаев, для которых предпочтительно не использовать @code:

• Для имен команд оболочки, таких как ls (используйте @command).
• Для ключей командной строки, таких как `-c', когда эти ключи употребляются сами по себе (используйте @option).
• Также, полная команда оболочки часто выглядит лучше, если ее набрать с использованием @samp, а не @code. В таком случае следует выбирать более приятный для глаз вариант.
• Для переменных среды, таких как `TEXINPUTS' (используйте @env).
• Для строки короче синтаксической лексемы. Например, если вы пишете о `goto-ch', что является только частью имени функции Emacs Lisp goto-char, вам следует использовать @samp.
• Вообще, когда вы пишете о знаках, используемых в лексеме; не применяйте @code, например, когда вы объясняете, какие буквы или печатные знаки могут использоваться в именах функций. (Применяйте @samp.) Также вы не должны применять @code для обозначения текста, рассматриваемого, как ввод для программы, если этот входной текст не написан на языке, похожем на язык программирования. Например, не нужно использовать @code для команд GNU Emacs, вводимых с клавиатуры (используйте вместо этого @kbd), хотя вы можете использовать @code для имен функций Emacs Lisp, которые вызываются этими командами.

Поскольку @command, @option, and @env были внесены в язык относительно недавно, возможно применение @code или @samp для имен команд, ключей и переменных среды. Новые команды позволяют выражать разметку более точно, но от использования старых команд нет действительного вреда, и конечно, давно написанные руководства используют их.

@kbd{символы-клавиатуры}

Используйте команду @kbd для символов ввода, которые печатает пользователь. Например, чтобы сослаться на символы M-a, напишите

@kbd{M-a}

а чтобы сослаться на символы M-x shell, напишите

@kbd{M-x shell}

Команда @kbd дает в Info такой же результат, как и @code, но в печатном руководстве она по умолчанию выводит другим шрифтом (наклонным равноширинным, вместо обычного равноширинного), так что пользователи могут отличить символы, которые предполагается вводить, от тех, что выводит компьютер.

Так как команда @kbd применяется в разных руководствах по-разному, вы можете управлять переключением шрифта для нее с помощью команды @kbdinputstyle. Эта команда не влияет на вывод Info. Пишите ее в начале строки с одним одним из этих слов в качестве аргумента:

`code'

Всегда использовать для @kbd тот же шрифт, что и для @code.

`example'

Использовать для @kbd другой шрифт только внутри блоков @example или в подобных случаях.

`distinct'

(по умолчанию) Всегда использовать для @kbd отличающийся шрифт.

Вы можете вставлять другие @-команды внутри фигурных скобок команды @kbd. Вот, например, способ оформить команду, которая можно было бы более подробно описать как "нажмите `r' и затем клавишу RET":

@kbd{r @key{RET}}

Это дает: r RET

Вы также используете команду @kbd, если выписываете вводимые буквы по одной; например:

Чтобы дать команду @code{logout},
напечатайте символы @kbd{l o g o u t @key{RET}}.

Это дает:

Чтобы дать команду logout, напечатайте символы l o g o u t RET.

(Этот пример показывает также, что вы можете добавить для ясности пробелы. Если вы действительно хотите упомянуть пробел как один из вводимых символов напишите для него @key{SPC}.)

@key{название-клавиши}

Используйте команду @key для общепринятых названий клавиш на клавиатуре, как например здесь:

@key{RET}

Вы можете использовать команду @key внутри аргумента команды @kbd, когда последовательность вводимых символов содержит одну или более клавиш, имеющих название.

Например, чтобы получить C-x ESC, вы написали бы:

@kbd{C-x @key{ESC}}

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

SPC

Пробел

RET

Возврат каретки

LFD

Перевод строки (однако, так как большинство современных клавиатур не имеют клавиши "Перевод строки", было бы лучше называть этот символ C-j.

TAB

Табуляция

BS

Забой

ESC

Выход

DEL

Удаление

SHIFT

Shift

CTRL

Control

META

Meta

Есть тонкости в обращении со словами вроде `meta' или `ctrl', которые являются названиями клавиш-модификаторов. При упоминании символа, в котором используется клавиша-модификатор, такого как Meta-a, используйте просто команду @kbd, не используйте @key; но если вы ссылаетесь на клавишу-модификатор саму по себе, используйте команду @key. Например, пишите `@kbd{Meta-a}', чтобы получить Meta-a и `@key{META}', чтобы получить META.

@samp{текст}

Используйте команду @samp для обозначения текста, являющегося буквальным примером или `образцом' последовательности символов в файле, строке, образце, etc. Заключайте этот текст в фигурные скобки. Аргумент выводится в одиночных кавычках как в Info-файле, так и в печатном руководстве; кроме того, в печатном руководстве он печатается равноширинным шрифтом.

Чтобы найти совпадения с @samp{foo} в конце строки, используйте
регулярное выражение @samp{foo$}.

дает

Чтобы найти совпадения с `foo' в конце строки, используйте регулярное выражение `foo$'.

Всякий раз, когда вы говорите об одиночных символах, используйте @samp, если @kbd и @key не более подходят к ситуации. Также, вы можете использовать @samp для полных выражений на Си и для полных команд оболочки -- в этом случае @samp часто выглядит лучше, чем @code. В основном, @samp -- это вариант для всего, что не покрывается @code, @kbd или @key.

Включайте знаки препинания в фигурные скобки, только если они являются частью задаваемой строки. Пишите знаки препинания вне фигурных скобок, если они являются частью английского текста(8), окружающего строку. В нижеследующем предложении, например, запятые и точки находятся вне фигурных скобок:

В английском гласными являются @samp{a}, @samp{e}, @samp{i},
@samp{o}, @samp{u} и иногда @samp{y}.

Это дает:

В английском гласными являются `a', `e', `i', `o', `u' и иногда `y'.

@var{метасинтаксическая-переменная}

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

Не используйте @var для имен конкретных переменных в языках программирования. Они являются определенными именами из программы, поэтому для них правильным будет использовать @code (ТјрзСћзш Сђўцшљ @code{пример-кода}). Например, переменная Emacs Lisp texinfo-tex-command -- не метасинтаксическая переменная; она правильно форматируется с использованием @code.

Также не используйте @var для переменных среды; для них необходима команда @env (смотрите следующий раздел).

Действие @var в Info-файле -- изменить регистр аргумента на верхний; в печатном руководстве и HTML -- выводить аргумент наклонным шрифтом.

Например,

Чтобы удалить файл @var{имя-файла},
напечатайте @samp{rm @var{имя-файла}}.

дает

Чтобы удалить файл имя-файла, напечатайте `rm имя-файла'.

(Заметьте, что @var может появиться внутри @code, @samp, @file, etc.)

Пишите метасинтаксические переменные полностью строчными буквами, без пробелов, и используйте дефисы, чтобы облегчить чтение. Таким образом, исходный Texinfo-текст для иллюстрации того, как начинать руководство в Texinfo, выглядит так:

\input texinfo
@@setfilename @var{имя-info-файла}
@@settitle @var{название-руководства}

Это дает:

\input texinfo
@setfilename имя-info-файла
@settitle название-руководства

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

..., напечатайте rm <имя-файла>

Однако этот стиль не используется в Texinfo. (Вы можете, конечно, если хотите, изменить исходный код `texinfo.tex' и команд форматирования для Info, чтобы они выводили в формате <...>.)

@env{переменная-среды}

Используйте команду @env для обозначения переменных среды, используемых во многих операционных системах, включая GNU. Не используйте ее для метасинтаксических переменных; вместо этого используйте @var (смотрите предыдущий раздел).

@env по действию эквивалентна @code. Например:

Переменная среды @env{PATH} задает путь поиска для команд.

дает

Переменная среды `PATH' задает путь поиска для команд.

@file{имя-файла}

Используйте команду @file для обозначения текста, являющегося именем файла, буфера или каталога, или именем ноды в Info. Вы также можете использовать эту команду для окончаний имен файлов. Не используйте @file для символов в языке программирования; используйте @code.

На данный момент @file по действию эквивалентна @samp. Например,

Файлы @file{.el} находятся
в каталоге @file{/usr/local/emacs/lisp}.

дает

Файлы `.el' находятся в каталоге `/usr/local/emacs/lisp'.

@command{имя-команды}

Используйте команду @command для обозначения имен команд, таких как ls или cc.

@command по своему действию эквивалентна @code. Например:

Команда @command{ls} печатает список содержимого каталога.

дает

Команда ls печатает список содержимого каталога.

Вы должны писать название программы шрифтом для обычного текста, если вы употребляете его как новое слово английского языка, например `Emacs' или `Bison'.)

При написании полного вызова команды оболочки, как `ls -l', вам следует использовать либо @samp, либо @code по своему усмотрению.

@option{имя-ключа}

Используйте команду @option для обозначения ключей командной строки, например -l, --version или --output=имя-файла.

@option по действию эквивалентна @samp. Например:

Ключ @option{-l} выдает длинный список.

дает

Ключ -l выдает длинный список.

В таблицах ключи выглядят лучше, если размечать их с помощью @code.

@dfn{термин}

Используйте команду @dfn для обозначения вводимого или определяемого термина. Применяйте эту команду только в тех отрывках, чья цель -- ввести термин, который будет использоваться впоследствии, или с которым читатель должен быть знаком. Просто первое упоминание термина не заслуживает @dfn. Эта команда выводит курсивом в печатном руководстве и в двойных кавычках в Info-файле. Например:

Избавление от файла называется @dfn{удалением}.

дает

Избавление от файла называется удалением.

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

@cite{ссылка}

Используйте команду @cite для названий книг, для которых нет сопутствующего Info-файла. Эта команда выводит курсивом в печатном руководстве и в двойных кавычках в Info-файле.

Если книга написана в Texinfo, лучше использовать команды перекрестных ссылок, чтобы читатель мог легко перейти по такой ссылке в Info. тјрзСћзш Сђўцшљ Команда @xref.

@acronym{аббревиатура}

Используйте команду @acronym для аббревиатур, записанных полностью заглавными буквами, таких как NASA. Аббревиатура задается в качестве единственного аргумента в фигурных скобках, например как `@acronym{NASA}'. По соображениям стиля или для определенной аббревиатуры вы можете предпочесть использовать точки, как здесь: `@acronym{Ф.Б.Р.}'.

В TeX и HTML аргумент печатается несколько уменьшенным шрифтом. В Info или простом текстовом выводе эта команда ничего не меняет.

@url{унифицированный-указатель-ресурса}

Используйте команду @url для обозначения унифицированных указателей ресурсов в World Wide Web. Она аналогична @file, @var, etc. и служит только для целей разметки. Она не создает ссылку, по которой вы можете перейти в HTML-выводе (для этого используйте команду @uref, ТјрзСћзш Сђўцшљ @uref{url[, отображаемый-текст]}). Эта команда полезна для url, не существующих на самом деле. Например:

Например, это мог бы быть url
@url{http://host.example.org/path}.

что дает:

Например, это мог бы быть url
http://host.example.org/path.

@email{адрес[, отображаемый-текст]}

Используйте команду @email для обозначения адреса электронной почты. Она принимает один обязательный аргумент, адрес, и один необязательный, отображаемый текст (по умолчанию это сам адрес).

В Info и TeX адрес показывается в угловых скобках после заданного отображаемого текста. В HTML, @email создает ссылку `mailto', которая обычно вызывает окно составления письма. Например:

Присылайте сообщения об ошибках по адресу
@email{bug-texinfo@@gnu.org}.  Присылайте предложения по
@email{bug-texinfo@@gnu.org, тому же адресу}.

дает

Присылайте сообщения об ошибках по адресу bug-texinfo@gnu.org.
Присылайте предложения по тому же адресу.

Логическое ударение

Обычно Texinfo изменяет шрифт для пометки слов в тексте в соответствии с категорией, к которой принадлежат эти слова; примером этого служит команда @code. Чаще всего это лучший способ пометки слов. Однако, иногда вы можете захотеть выделить текст, не указывая его категорию. В Texinfo для этого есть две команды. Также, в Texinfo есть несколько команд для задания шрифта, которым TeX будет набирать текст. Эти команды не затрагивают Info, и только одна из них, команда @r, имеет обычное употребление.

@emph{текст} и @strong{текст}

Команды @emph и @strong используются для обозначения логического ударения; @strong сильнее. В печатном выводе @emph производит курсив, а @strong дает жирный шрифт.

Например,

@quotation
@strong{Осторожно:} @samp{rm * .[^.]*} удаляет @emph{все}
файлы в каталоге.
@end quotation

дает в печатном выводе следующее:

Осторожно: `rm * .[^.]*' удаляет все файлы в каталоге.

и следующее в Info:

     *Осторожно*: `rm * .[^.]*' удаляет _все_
     файлы в каталоге.

Команда @strong используется редко, за исключением случаев, когда нужно пометить нечто, являющееся в действительности типографическим элементом, таким как слово `Осторожно' в предыдущем примере.

В Info-файле, @emph окружает текст символами подчеркивания, `_', а @strong помещает вокруг текста звездочки.

Осторожно: Не используйте @strong со словом `Note'; Info ошибочно примет это за перекрестную ссылку. Используйте вместо этого фразы вроде Please note или Caution.

@sc{текст}: Шрифт маленьких заглавных букв

Используйте команду `@sc', чтобы получить текст, набранный в печатном выводе и в HTML шрифтом маленьких заглавных букв, а в Info-файле напечатанный заглавными буквами. Пишите желаемый текст строчными буквами в фигурных скобках, как здесь:

@sc{acm} и @sc{ieee} --- технические сообщества.

Это дает:

ACM и IEEE -- технические сообщества.

TeX набирает маленькие заглавные буквы так, чтобы буквы на странице не `выскакивали на вас'. Это облегчает чтение текста, набранного маленькими заглавными буквами по сравнению с набранным полностью в верхнем регистре, но обычно все-таки лучше использовать обычный текст смешанного регистра. Команды форматирования Info выводят текст маленьких заглавных букв в верхнем регистре. В HTML текст выводится заглавными буквами, и для его отображения используется меньший шрифт.

Если текст внутри фигурных скобок команды @sc в верхнем регистре, TeX набирает его ПОЛНЫМИ ЗАГЛАВНЫМИ БУКВАМИ. Используйте полные заглавные буквы умеренно или не используйте вообще; поскольку бессмысленно помечать командой @sc текст, набранный полностью заглавными буквами, makeinfo предупреждает о таких случаях.

Вы также можете применять шрифт маленьких заглавных букв для жаргонных слов, таких как ATO (слово из NASA, обозначающее `abort to orbit').

Есть некие тонкости в использовании шрифта маленьких заглавных букв с жаргонными словами, вроде CDR; это слово применяется в программировании на Лиспе. В таком случае вы должны использовать шрифт маленьких заглавных букв, когда это слово относится ко второму и последующим элементам списка (CDR списка), но должны использовать `@code', когда это слово относится к имени функции Лиспа с таким же написанием.

Шрифты печати

Texinfo предоставляет четыре команды, изменяющие шрифт в печатном руководстве, но не влияющие на Info-файл. @i устанавливает курсив (в некоторых версиях TeX используется наклонный шрифт), @b устанавливает жирный шрифт, @t устанавливает равноширинный шрифт в стиле печатной машинки, используемый @code, а @r устанавливает романский шрифт, обычный шрифт, которым печатается весь текст. Все четыре команды действуют на следующий за ними аргумент, заключенный в фигурные скобки.

Частое применение находит только команда @r: в примерах программ вы можете использовать команду @r для перевода комментариев из равноширинного шрифта в романский. Это смотрится лучше в печатном выводе.

Например,

@lisp
(+ 2 2)    ; @r{Складывает два и два.}
@end lisp

дает

(+ 2 2)    ; Складывает два и два.

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