Цитаты и примеры

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

В Texinfo вы всегда начинаете цитату или пример, написав @-команду в начале отдельной строки, и завершаете написанием команды @end также в начале отдельной строки. Скажем, вы начинаете пример, записывая с новой строки команду @example, и завершаете написанием команды @end example на отдельной строке так же в ее начале.

Команды ограничения блока

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

@quotation

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

@example

Показывает код, команды и подобные вещи. Текст печатается равноширинным шрифтом и смещается вправо, но не заполняется.

@smallexample

Показывает код, команды и подобные вещи. Подобно @example, только в TeX эта команда набирает текст более мелким шрифтом для формата @smallbook, меньшего, чем формат 8.5 на 11 дюймов.

@lisp

Как @example, но специально для иллюстрации кода на Лиспе. Текст печатается равноширинным шрифтом и смещается вправо, но не заполняется.

@smalllisp

То же для @lisp, что и @smallexample для @example.

@display

Показывает иллюстративный текст. Текст смещается вправо и заполняется, шрифт не меняется (то есть по умолчанию используется романский).

@smalldisplay

То же для @display, что и @smallexample для @example.

@format

Как @display (текст не заполняется, шрифт не изменяется), но отступ не делается.

@smallformat

То же для @format, что и @smallexample для @example.

Внутри перечисленных конструкций можно использовать команду @exdent для отмены смещения строки вправо.

Команды @flushleft и @flushright служат для выравнивания незаполненного текста по левому или правому полю.

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

Для выделения примера или цитаты вы можете использовать с одной из вышеперечисленных конструкций команду @cartouche, которая нарисует вокруг них рамку с закругленными углами. See section Рисование рамок вокруг примеров.

@quotation

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

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

Это пример текста, написанного между командами @quotation и @end quotation. Команда @quotation чаще всего применяется для обозначения того, что данный фрагмент текста взят из другого (настоящего или гипотетического) печатного произведения.

Пишите команду @quotation на отдельной строке. Эта строка исчезнет при выводе. Отмечайте конец цитаты строкой, начинающейся командой @end quotation и не содержащей ничего больше. Строка @end quotation также не выводится. Таким образом, такой текст:

@quotation
Это
нечто.
@end quotation

дает при выводе

Это нечто.

@example

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

Это пример текста, записанного между
командой @example
и командой @end example.
В этом тексте сделаны отступы, но не сделано заполнение.

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

Пишите команду @example в начале отдельной строки. Отмечайте конец примера командой @end example также записанной в начале отдельной строки.

Например,

@example
mv foo bar
@end example

дает

mv foo bar

Строки, содержащие @example и @end example, не выводятся. Чтобы вывод смотрелся хорошо, вы должны поместить пустую строку перед командой @example и другую после @end example. Заметьте, что все пустые строки внутри блока @example появятся при выводе.

Внимание: Не используйте символы табуляции внутри текста примера (и вообще в Texinfo-файлах)! TeX воспринимает символы табуляции как один пробел, и это не похоже на табуляцию. Это проблема TeX. (Если необходимо, вы можете использовать M-x untabify в Emacs для превращения всех символов табуляции в области в пробелы.)

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

(Для примеров, включенных в предложение, а не отделенных от предшествующего и последующего текста, применяется команда @code. See section @code{пример-кода}.)

@noindent

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

Например:

@example
Это пример
@end example

@noindent
В этой строке нет отступа.  Как вы видите, начало этой строки
смещено до предела влево, как и в следующей строке.  (Весь пример
целиком заключен между @code{@@display} и @code{@@end display}.)

дает при выводе

Это пример


В этой строке нет отступа.  Как вы видите, начало этой строки
смещено до предела влево, как и в следующей строке.  (Весь пример
целиком заключен между @display и @end display.)

При точной настройке числа пустых строк в выводе Info, помните, что строка, содержащая @noindent, не производит пустую строку, как и строка @end example.

В исходном Texinfo-файле этого руководства перед каждой строкой, говорящей `дает', написана строка с командой @noindent.

Не пишите фигурные скобки после команды @noindent; они не обязательны, так как @noindent используется вне абзаца (see section Синтаксис @-команд).

@lisp

Для примеров на Лиспе используется команда @lisp. Она является синонимом команды @example.

Это пример текста, написанного между командами @lisp и
@end lisp.

Используйте команду @lisp вместо @example, чтобы сохранить информацию о природе примера. Это полезно, например, если вы пишите функцию, вычисляющую весь Лисп-код в Texinfo-файле. После этого вы можете использовать Texinfo-файл в качестве библиотеки Лиспа.(7)

Отмечайте конец блока @lisp командой @end lisp, записанной на отдельной строке.

Команды блоков @small...

Кроме обычных команд @example и @lisp в Texinfo определены "маленькие" команды в стиле примера. Это команды @smalldisplay, @smallexample, @smallformat и @smalllisp. Все они разработаны для использования вместе с командой @smallbook, заставляющей TeX выводить печатную книгу в формате 7 на 9.25 дюймов, а не в обычном формате 8.5 на 11.

В TeX, команды @small... набирают текст для маленького формата @smallbook более мелким шрифтом, чем для формата 8.5 на 11 дюймов. Следовательно, многие примеры, содержащие длинные строки, умещаются на более узкой странице формата @smallbook без необходимости укорочения. Обе команды набирают текст шрифтом обычного размера, когда вы форматируете для формата размером 8.5 на 11 дюймов; на самом деле, в этой ситуации команды @small... определены эквивалентными соответствующим командам без small.

В Info команды @small... эквивалентны соответствующим командам без small.

Помечайте конец блока @small... парной командой @end small.... Например, пишите для @smallexample парную ей @end smallexample.

Вот пример тектса, написанный маленьким шрифтом, используемым командами @smallexample и @smalllisp:

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

Обычно печатный документ смотрится лучше, если вы используете в главе только одну из команд, к примеру, или @example, или @smallexample. Как можно реже используйте оба формата вперемежку.

See section Печать "маленьких" книг, для получения подробной информации о команде @smallbook.

@display и @smalldisplay

Команда @display начинает текст, подобный примеру. Она похожа на команду @example, только команда @display не использует в печатном руководстве равноширинный шрифт. На самом деле, она не задает никакого шрифта, то есть текст выводится тем же шрифтом, каким бы он выводился без команды @display.

Это пример текста, написанного между командами @display и
@end display.  Команда @display делает в тексте
отступы, но не заполняет его.

Texinfo также предоставляет команду @smalldisplay, которая похожа на @display но использует в формате @smallbook меньший шрифт. See section Команды блоков @small....

@format и @smallformat

Команда @format похожа на команду @example за исключением того, что @format не сужает поля.

Это пример текста,
           написанного между командами
                             @format и @end format.
Как вы видите
            из этого примера, команда
                              @format не заполняет текст.

Texinfo также предоставляет команду @smallformat, которая похожа на @format, но использует в формате @smallbook меньший шрифт. See section Команды блоков @small....

@exdent: Отмена отступа в строке

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

@exdent обычно применяется в примерах. Таким образом,

@example
Эта строка написана после команды @@example.
@exdent В этой строке отменен отступ.
Эта строка написана после строки с отмененным отступом.
@@end example идет на следующей строке.

дает

Эта строка написана после команды @example.
В этой строке отменен отступ.
Эта строка написана после строки с отмененным отступом.
@end example идет на следующей строке.

На практике команда @exdent применяется редко. Обычно отступ отменяется завершением примера и возвратом к обычной ширине страницы.

@flushleft и @flushright

Команды @flushleft и @flushright выравнивают концы строк по левому и правому краю страницы, но не заполняют текст. Эти команды пишутся на отдельных строках, без фигурных скобок. Действие команд @flushleft и @flushright прекращается командами @end flushleft и @end flushright, написанными на отдельных строках.

Например,

@flushleft
Этот текст
прижат влево.
@end flushleft

дает

Этот текст
прижат влево.

@flushright создает тип отступов, часто используемый для обратного адреса в письмах. Например,

@flushright
Вот пример текста, прижатого
вправо.  Команда @code{@flushright}
смещает каждую строку к правому краю, но
оставляет левые концы неровными.
@end flushright

дает

Вот пример текста, прижатого
вправо.  Команда @flushright
смещает каждую строку к правому краю, но
оставляет левые концы неровными.

Рисование рамок вокруг примеров

Команда @cartouche рисует в печатном руководстве рамку с закругленными углами вокруг своего содержимого. Вы можете использовать эту команду для большего выделения примера или цитаты. Например, вы можете написать руководство, в котором какой-нибудь тип примеров окружается рамкой для заострения внимания читателя.

@cartouche влияет только на печатное руководство; она не играет роли в других выходных форматах.

Например,

@example
@cartouche
% pwd
/usr/local/share/emacs
@end cartouche
@end example

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

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

% pwd
/usr/local/lib/emacs/info

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