1 This is ../info/texinfo.info, produced by makeinfo version 4.0b from
4 INFO-DIR-SECTION Texinfo documentation system
6 * Texinfo: (texinfo). The GNU documentation format.
7 * install-info: (texinfo)Invoking install-info. Updating info/dir entries.
8 * texi2dvi: (texinfo)Format with texi2dvi. Printing Texinfo documentation.
9 * texindex: (texinfo)Format with tex/texindex. Sorting Texinfo index files.
10 * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source.
13 This file documents Texinfo, a documentation system that can produce
14 both on-line information and a printed manual from a single source file.
16 Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98 Free Software
19 This edition is for Texinfo version 3.12.
21 Permission is granted to make and distribute verbatim copies of this
22 manual provided the copyright notice and this permission notice are
23 preserved on all copies.
25 Permission is granted to copy and distribute modified versions of this
26 manual under the conditions for verbatim copying, provided that the
27 entire resulting derived work is distributed under the terms of a
28 permission notice identical to this one.
30 Permission is granted to copy and distribute translations of this
31 manual into another language, under the above conditions for modified
32 versions, except that this permission notice may be stated in a
33 translation approved by the Free Software Foundation.
36 File: texinfo.info, Node: ftable vtable, Next: itemx, Prev: table, Up: Two-column Tables
38 `@ftable' and `@vtable'
39 -----------------------
41 The `@ftable' and `@vtable' commands are the same as the `@table'
42 command except that `@ftable' automatically enters each of the items in
43 the first column of the table into the index of functions and `@vtable'
44 automatically enters each of the items in the first column of the table
45 into the index of variables. This simplifies the task of creating
46 indices. Only the items on the same line as the `@item' commands are
47 indexed, and they are indexed in exactly the form that they appear on
48 that line. *Note Creating Indices: Indices, for more information about
51 Begin a two-column table using `@ftable' or `@vtable' by writing the
52 @-command at the beginning of a line, followed on the same line by an
53 argument that is a Texinfo command such as `@code', exactly as you
54 would for an `@table' command; and end the table with an `@end ftable'
55 or `@end vtable' command on a line by itself.
57 See the example for `@table' in the previous section.
60 File: texinfo.info, Node: itemx, Prev: ftable vtable, Up: Two-column Tables
65 Use the `@itemx' command inside a table when you have two or more
66 first column entries for the same item, each of which should appear on a
67 line of its own. Use `@itemx' for all but the first entry; `@itemx'
68 should always follow an `@item' command. The `@itemx' command works
69 exactly like `@item' except that it does not generate extra vertical
70 space above the first column text.
77 These two functions accept a character or a string as
78 argument, and return the corresponding upper case (lower
79 case) character or string.
86 These two functions accept a character or a string as argument,
87 and return the corresponding upper case (lower case) character or
90 (Note also that this example illustrates multi-line supporting text in
94 File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables
99 `@multitable' allows you to construct tables with any number of
100 columns, with each column having any width you like.
102 You define the column widths on the `@multitable' line itself, and
103 write each row of the actual table following an `@item' command, with
104 columns separated by an `@tab' command. Finally, `@end multitable'
105 completes the table. Details in the sections below.
109 * Multitable Column Widths:: Defining multitable column widths.
110 * Multitable Rows:: Defining multitable rows, with examples.
113 File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Prev: Multi-column Tables, Up: Multi-column Tables
115 Multitable Column Widths
116 ------------------------
118 You can define the column widths for a multitable in two ways: as
119 fractions of the line length; or with a prototype row. Mixing the two
120 methods is not supported. In either case, the widths are defined
121 entirely on the same line as the `@multitable' command.
123 1. To specify column widths as fractions of the line length, write
124 `@columnfractions' and the decimal numbers (presumably less than
125 1) after the `@multitable' command, as in:
127 @multitable @columnfractions .33 .33 .33
129 The fractions need not add up exactly to 1.0, as these do not.
130 This allows you to produce tables that do not need the full line
133 2. To specify a prototype row, write the longest entry for each column
134 enclosed in braces after the `@multitable' command. For example:
136 @multitable {some text for column one} {for column two}
138 The first column will then have the width of the typeset `some
139 text for column one', and the second column the width of `for
142 The prototype entries need not appear in the table itself.
144 Although we used simple text in this example, the prototype
145 entries can contain Texinfo commands; markup commands such as
146 `@code' are particularly likely to be useful.
150 File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables
155 After the `@multitable' command defining the column widths (see the
156 previous section), you begin each row in the body of a multitable with
157 `@item', and separate the column entries with `@tab'. Line breaks are
158 not special within the table body, and you may break input lines in
159 your source file as necessary.
161 Here is a complete example of a multi-column table (the text is from
162 `The XEmacs Users' Manual', *note Splitting Windows: (xemacs)Split
165 @multitable @columnfractions .15 .45 .4
166 @item Key @tab Command @tab Description
168 @tab @code{split-window-vertically}
169 @tab Split the selected window into two windows,
170 with one above the other.
172 @tab @code{split-window-horizontally}
173 @tab Split the selected window into two windows
174 positioned side by side.
177 @tab In the mode line or scroll bar of a window,
183 Key Command Description
184 C-x 2 `split-window-vertically' Split the selected window
185 into two windows, with one
187 C-x 3 `split-window-horizontally' Split the selected window
188 into two windows positioned
190 C-Mouse-2 In the mode line or scroll
191 bar of a window, split that
195 File: texinfo.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top
200 Using Texinfo, you can generate indices without having to sort and
201 collate entries manually. In an index, the entries are listed in
202 alphabetical order, together with information on how to find the
203 discussion of each entry. In a printed manual, this information
204 consists of page numbers. In an Info file, this information is a menu
205 entry leading to the first node referenced.
207 Texinfo provides several predefined kinds of index: an index for
208 functions, an index for variables, an index for concepts, and so on.
209 You can combine indices or use them for other than their canonical
210 purpose. If you wish, you can define your own indices.
214 * Index Entries:: Choose different words for index entries.
215 * Predefined Indices:: Use different indices for different kinds
217 * Indexing Commands:: How to make an index entry.
218 * Combining Indices:: How to combine indices.
219 * New Indices:: How to define your own indices.
222 File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: Indices, Up: Indices
227 When you are making index entries, it is good practice to think of the
228 different ways people may look for something. Different people _do
229 not_ think of the same words when they look something up. A helpful
230 index will have items indexed under all the different words that people
231 may use. For example, one reader may think it obvious that the
232 two-letter names for indices should be listed under "Indices,
233 two-letter names", since the word "Index" is the general concept. But
234 another reader may remember the specific concept of two-letter names
235 and search for the entry listed as "Two letter names for indices". A
236 good index will have both entries and will help both readers.
238 Like typesetting, the construction of an index is a highly skilled,
239 professional art, the subtleties of which are not appreciated until you
240 need to do it yourself.
242 *Note Printing Indices & Menus::, for information about printing an
243 index at the end of a book or creating an index menu in an Info file.
246 File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices
251 Texinfo provides six predefined indices:
253 * A "concept index" listing concepts that are discussed.
255 * A "function index" listing functions (such as entry points of
258 * A "variables index" listing variables (such as global variables of
261 * A "keystroke index" listing keyboard commands.
263 * A "program index" listing names of programs.
265 * A "data type index" listing data types (such as structures defined
268 Not every manual needs all of these, and most manuals use two or three
269 of them. This manual has two indices: a concept index and an @-command
270 index (that is actually the function index but is called a command
271 index in the chapter heading). Two or more indices can be combined
272 into one using the `@synindex' or `@syncodeindex' commands. *Note
276 File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices
278 Defining the Entries of an Index
279 ================================
281 The data to make an index come from many individual indexing commands
282 scattered throughout the Texinfo source file. Each command says to add
283 one entry to a particular index; after formatting, the index will give
284 the current page number or node name as the reference.
286 An index entry consists of an indexing command at the beginning of a
287 line followed, on the rest of the line, by the entry.
289 For example, this section begins with the following five entries for
292 @cindex Defining indexing entries
293 @cindex Index entries
294 @cindex Entries for an index
295 @cindex Specifying index entries
296 @cindex Creating index entries
298 Each predefined index has its own indexing command--`@cindex' for the
299 concept index, `@findex' for the function index, and so on.
301 Concept index entries consist of text. The best way to write an index
302 is to choose entries that are terse yet clear. If you can do this, the
303 index often looks better if the entries are not capitalized, but
304 written just as they would appear in the middle of a sentence.
305 (Capitalize proper names and acronyms that always call for upper case
306 letters.) This is the case convention we use in most GNU manuals'
309 If you don't see how to make an entry terse yet clear, make it longer
310 and clear--not terse and confusing. If many of the entries are several
311 words long, the index may look better if you use a different convention:
312 to capitalize the first word of each entry. But do not capitalize a
313 case-sensitive name such as a C or Lisp function name or a shell
314 command; that would be a spelling error.
316 Whichever case convention you use, please use it consistently!
318 Entries in indices other than the concept index are symbol names in
319 programming languages, or program names; these names are usually
320 case-sensitive, so use upper and lower case as required for them.
322 By default, entries for a concept index are printed in a small roman
323 font and entries for the other indices are printed in a small `@code'
324 font. You may change the way part of an entry is printed with the
325 usual Texinfo commands, such as `@file' for file names and `@emph' for
326 emphasis (*note Marking Text::).
328 The six indexing commands for predefined indices are:
331 Make an entry in the concept index for CONCEPT.
334 Make an entry in the function index for FUNCTION.
337 Make an entry in the variable index for VARIABLE.
340 Make an entry in the key index for KEYSTROKE.
343 Make an entry in the program index for PROGRAM.
346 Make an entry in the data type index for DATA TYPE.
348 *Caution:* Do not use a colon in an index entry. In Info, a colon
349 separates the menu entry name from the node name. An extra colon
350 confuses Info. *Note The Parts of a Menu: Menu Parts, for more
351 information about the structure of a menu entry.
353 If you write several identical index entries in different places in a
354 Texinfo file, the index in the printed manual will list all the pages to
355 which those entries refer. However, the index in the Info file will
356 list *only* the node that references the *first* of those index
357 entries. Therefore, it is best to write indices in which each entry
358 refers to only one place in the Texinfo file. Fortunately, this
359 constraint is a feature rather than a loss since it means that the index
360 will be easy to use. Otherwise, you could create an index that lists
361 several pages for one entry and your reader would not know to which page
362 to turn. If you have two identical entries for one topic, change the
363 topics slightly, or qualify them to indicate the difference.
365 You are not actually required to use the predefined indices for their
366 canonical purposes. For example, suppose you wish to index some C
367 preprocessor macros. You could put them in the function index along
368 with actual functions, just by writing `@findex' commands for them;
369 then, when you print the "Function Index" as an unnumbered chapter, you
370 could give it the title `Function and Macro Index' and all will be
371 consistent for the reader. Or you could put the macros in with the
372 data types by writing `@tindex' commands for them, and give that index
373 a suitable title so the reader will understand. (*Note Printing
377 File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices
382 Sometimes you will want to combine two disparate indices such as
383 functions and concepts, perhaps because you have few enough of one of
384 them that a separate index for them would look silly.
386 You could put functions into the concept index by writing `@cindex'
387 commands for them instead of `@findex' commands, and produce a
388 consistent manual by printing the concept index with the title
389 `Function and Concept Index' and not printing the `Function Index' at
390 all; but this is not a robust procedure. It works only if your
391 document is never included as part of another document that is designed
392 to have a separate function index; if your document were to be included
393 with such a document, the functions from your document and those from
394 the other would not end up together. Also, to make your function names
395 appear in the right font in the concept index, you would need to
396 enclose every one of them between the braces of `@code'.
400 * syncodeindex:: How to merge two indices, using `@code'
401 font for the merged-from index.
402 * synindex:: How to merge two indices, using the
403 default font of the merged-to index.
406 File: texinfo.info, Node: syncodeindex, Next: synindex, Prev: Combining Indices, Up: Combining Indices
411 When you want to combine functions and concepts into one index, you
412 should index the functions with `@findex' and index the concepts with
413 `@cindex', and use the `@syncodeindex' command to redirect the function
414 index entries into the concept index.
416 The `@syncodeindex' command takes two arguments; they are the name of
417 the index to redirect, and the name of the index to redirect it to.
418 The template looks like this:
420 @syncodeindex FROM TO
422 For this purpose, the indices are given two-letter names:
442 Write an `@syncodeindex' command before or shortly after the
443 end-of-header line at the beginning of a Texinfo file. For example, to
444 merge a function index with a concept index, write the following:
448 This will cause all entries designated for the function index to merge
449 in with the concept index instead.
451 To merge both a variables index and a function index into a concept
452 index, write the following:
457 The `@syncodeindex' command puts all the entries from the `from'
458 index (the redirected index) into the `@code' font, overriding whatever
459 default font is used by the index to which the entries are now
460 directed. This way, if you direct function names from a function index
461 into a concept index, all the function names are printed in the `@code'
462 font as you would expect.
465 File: texinfo.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices
470 The `@synindex' command is nearly the same as the `@syncodeindex'
471 command, except that it does not put the `from' index entries into the
472 `@code' font; rather it puts them in the roman font. Thus, you use
473 `@synindex' when you merge a concept index into a function index.
475 *Note Printing Indices & Menus::, for information about printing an
476 index at the end of a book or creating an index menu in an Info file.
479 File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices
484 In addition to the predefined indices, you may use the `@defindex'
485 and `@defcodeindex' commands to define new indices. These commands
486 create new indexing @-commands with which you mark index entries. The
487 `@defindex 'command is used like this:
491 The name of an index should be a two letter word, such as `au'. For
496 This defines a new index, called the `au' index. At the same time,
497 it creates a new indexing command, `@auindex', that you can use to make
498 index entries. Use the new indexing command just as you would use a
499 predefined indexing command.
501 For example, here is a section heading followed by a concept index
502 entry and two `au' index entries.
504 @section Cognitive Semantics
505 @cindex kinesthetic image schemas
506 @auindex Johnson, Mark
507 @auindex Lakoff, George
509 (Evidently, `au' serves here as an abbreviation for "author".) Texinfo
510 constructs the new indexing command by concatenating the name of the
511 index with `index'; thus, defining an `au' index leads to the automatic
512 creation of an `@auindex' command.
514 Use the `@printindex' command to print the index, as you do with the
515 predefined indices. For example:
517 @node Author Index, Subject Index, , Top
518 @unnumbered Author Index
522 The `@defcodeindex' is like the `@defindex' command, except that, in
523 the printed output, it prints entries in an `@code' font instead of a
524 roman font. Thus, it parallels the `@findex' command rather than the
527 You should define new indices within or right after the end-of-header
528 line of a Texinfo file, before any `@synindex' or `@syncodeindex'
529 commands (*note Header::).
532 File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top
537 Texinfo provides several commands for inserting characters that have
538 special meaning in Texinfo, such as braces, and for other graphic
539 elements that do not correspond to simple characters you can type.
543 * Braces Atsigns:: How to insert braces, `@'.
544 * Inserting Space:: How to insert the right amount of space
546 * Inserting Accents:: How to insert accents and special characters.
547 * Dots Bullets:: How to insert dots and bullets.
548 * TeX and copyright:: How to insert the TeX logo
549 and the copyright symbol.
550 * pounds:: How to insert the pounds currency symbol.
551 * minus:: How to insert a minus sign.
552 * math:: How to format a mathematical expression.
553 * Glyphs:: How to indicate results of evaluation,
554 expansion of macros, errors, etc.
555 * Images:: How to include graphics.
558 File: texinfo.info, Node: Braces Atsigns, Next: Inserting Space, Prev: Insertions, Up: Insertions
560 Inserting @ and Braces
561 ======================
563 `@' and curly braces are special characters in Texinfo. To insert
564 these characters so they appear in text, you must put an `@' in front
565 of these characters to prevent Texinfo from misinterpreting them.
567 Do not put braces after any of these commands; they are not necessary.
571 * Inserting An Atsign:: How to insert `@'.
572 * Inserting Braces:: How to insert `{' and `}'.
575 File: texinfo.info, Node: Inserting An Atsign, Next: Inserting Braces, Prev: Braces Atsigns, Up: Braces Atsigns
577 Inserting `@' with @@
578 ---------------------
580 `@@' stands for a single `@' in either printed or Info output.
582 Do not put braces after an `@@' command.
585 File: texinfo.info, Node: Inserting Braces, Prev: Inserting An Atsign, Up: Braces Atsigns
587 Inserting `{' and `}'with @{ and @}
588 -----------------------------------
590 `@{' stands for a single `{' in either printed or Info output.
592 `@}' stands for a single `}' in either printed or Info output.
594 Do not put braces after either an `@{' or an `@}' command.
597 File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Braces Atsigns, Up: Insertions
602 The following sections describe commands that control spacing of
603 various kinds within and after sentences.
607 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
608 * Ending a Sentence:: Sometimes it does.
609 * Multiple Spaces:: Inserting multiple spaces.
610 * dmn:: How to format a dimension.
613 File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Inserting Space, Up: Inserting Space
615 Not Ending a Sentence
616 ---------------------
618 Depending on whether a period or exclamation point or question mark is
619 inside or at the end of a sentence, less or more space is inserted after
620 a period in a typeset manual. Since it is not always possible for
621 Texinfo to determine when a period ends a sentence and when it is used
622 in an abbreviation, special commands are needed in some circumstances.
623 (Usually, Texinfo can guess how to handle periods, so you do not need to
624 use the special commands; you just enter a period as you would if you
625 were using a typewriter, which means you put two spaces after the
626 period, question mark, or exclamation mark that ends a sentence.)
628 Use the `@:' command after a period, question mark, exclamation mark,
629 or colon that should not be followed by extra space. For example, use
630 `@:' after periods that end abbreviations which are not at the ends of
635 The s.o.p.@: has three parts ...
636 The s.o.p. has three parts ...
640 The s.o.p. has three parts ...
641 The s.o.p. has three parts ...
643 (Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
646 `@:' has no effect on the Info output. Do not put braces after `@:'.
649 File: texinfo.info, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space
654 Use `@.' instead of a period, `@!' instead of an exclamation point,
655 and `@?' instead of a question mark at the end of a sentence that ends
656 with a single capital letter. Otherwise, TeX will think the letter is
657 an abbreviation and will not insert the correct end-of-sentence
658 spacing. Here is an example:
660 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.
661 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
665 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
666 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
668 In the Info file output, `@.' is equivalent to a simple `.'; likewise
671 The meanings of `@:' and `@.' in Texinfo are designed to work well
672 with the Emacs sentence motion commands (*note Sentences:
673 (xemacs)Sentences.). This made it necessary for them to be
674 incompatible with some other formatting systems that use @-commands.
676 Do not put braces after any of these commands.
679 File: texinfo.info, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space
684 Ordinarily, TeX collapses multiple whitespace characters (space, tab,
685 and newline) into a single space. Info output, on the other hand,
686 preserves whitespace as you type it, except for changing a newline into
687 a space; this is why it is important to put two spaces at the end of
688 sentences in Texinfo documents.
690 Occasionally, you may want to actually insert several consecutive
691 spaces, either for purposes of example (what your program does with
692 multiple spaces as input), or merely for purposes of appearance in
693 headings or lists. Texinfo supports three commands: `@SPACE', `@TAB',
694 and `@NL', all of which insert a single space into the output. (Here,
695 `@SPACE' represents an `@' character followed by a space, i.e., `@ ',
696 and `TAB' and `NL' represent the tab character and end-of-line, i.e.,
697 when `@' is the last character on a line.)
707 Other possible uses of `@SPACE' have been subsumed by `@multitable'
708 (*note Multi-column Tables::).
710 Do not follow any of these commands with braces.
713 File: texinfo.info, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space
715 `@dmn'{DIMENSION}: Format a Dimension
716 -------------------------------------
718 At times, you may want to write `12pt' or `8.5in' with little or no
719 space between the number and the abbreviation for the dimension. You
720 can use the `@dmn' command to do this. On seeing the command, TeX
721 inserts just enough space for proper typesetting; the Info formatting
722 commands insert no space at all, since the Info file does not require
725 To use the `@dmn' command, write the number and then follow it
726 immediately, with no intervening space, by `@dmn', and then by the
727 dimension within braces. For example,
729 A4 paper is 8.27@dmn{in} wide.
733 A4 paper is 8.27in wide.
735 Not everyone uses this style. Some people prefer `8.27 in.@:' or
736 `8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases,
737 however, the formatters may insert a line break between the number and
738 the dimension, so use `@w' (*note w::). Also, if you write a period
739 after an abbreviation within a sentence, you should write `@:' after
740 the period to prevent TeX from inserting extra whitespace, as shown
741 here. *Note Inserting Space::.
744 File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions
749 Here is a table with the commands Texinfo provides for inserting
750 floating accents. The commands with non-alphabetic names do not take
751 braces around their argument (which is taken to be the next character).
752 (Exception: `@,' _does_ take braces around its argument.) This is so
753 as to make the source as convenient to type and read as possible, since
754 accented characters are very common in some languages.
759 @,{c} c, cedilla accent
760 @=o o= macron/overbar accent
761 @^o o^ circumflex accent
764 @dotaccent{o} o. overdot accent
765 @H{o} o'' long Hungarian umlaut
766 @ringaccent{o} o* ring accent
767 @tieaccent{oo} oo[ tie-after accent
768 @u{o} o( breve accent
769 @ubaraccent{o} o_ underbar accent
770 @udotaccent{o} .o underdot accent
771 @v{o} o< hacek or check accent
773 This table lists the Texinfo commands for inserting other characters
774 commonly used in languages other than English.
776 @exclamdown{} ! upside-down !
777 @questiondown{} ? upside-down ?
778 @aa{},@AA{} aa,AA A,a with circle
779 @ae{},@AE{} ae,AE ae,AE ligatures
780 @dotless{i} i dotless i
781 @dotless{j} j dotless j
782 @l{},@L{} /l,/L suppressed-L,l
783 @o{},@O{} /o,/O O,o with slash
784 @oe{},@OE{} oe,OE OE,oe ligatures
785 @ss{} ss es-zet or sharp S
788 File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions
790 Inserting Ellipsis, Dots, and Bullets
791 =====================================
793 An "ellipsis" (a line of dots) is not typeset as a string of periods,
794 so a special command is used for ellipsis in Texinfo. The `@bullet'
795 command is special, too. Each of these commands is followed by a pair
796 of braces, `{}', without any whitespace between the name of the command
797 and the braces. (You need to use braces with these commands because
798 you can use them next to other text; without the braces, the formatters
799 would be confused. *Note @-Command Syntax: Command Syntax, for further
804 * dots:: How to insert dots ...
805 * bullet:: How to insert a bullet.
808 File: texinfo.info, Node: dots, Next: bullet, Prev: Dots Bullets, Up: Dots Bullets
813 Use the `@dots{}' command to generate an ellipsis, which is three
814 dots in a row, appropriately spaced, like this: `...'. Do not simply
815 write three periods in the input file; that would work for the Info
816 file output, but would produce the wrong amount of space between the
817 periods in the printed manual.
819 Similarly, the `@enddots{}' command generates an end-of-sentence
820 ellipsis (four dots) ....
823 File: texinfo.info, Node: bullet, Prev: dots, Up: Dots Bullets
828 Use the `@bullet{}' command to generate a large round dot, or the
829 closest possible thing to one. In Info, an asterisk is used.
833 When you use `@bullet' in `@itemize', you do not need to type the
834 braces, because `@itemize' supplies them. (*Note `@itemize': itemize.)
837 File: texinfo.info, Node: TeX and copyright, Next: pounds, Prev: Dots Bullets, Up: Insertions
839 Inserting TeX and the Copyright Symbol
840 ======================================
842 The logo `TeX' is typeset in a special fashion and it needs an
843 @-command. The copyright symbol, `(C)', is also special. Each of
844 these commands is followed by a pair of braces, `{}', without any
845 whitespace between the name of the command and the braces.
849 * tex:: How to insert the TeX logo.
850 * copyright symbol:: How to use `@copyright'{}.
853 File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright
858 Use the `@TeX{}' command to generate `TeX'. In a printed manual,
859 this is a special logo that is different from three ordinary letters.
860 In Info, it just looks like `TeX'. The `@TeX{}' command is unique
861 among Texinfo commands in that the `T' and the `X' are in upper case.
864 File: texinfo.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright
869 Use the `@copyright{}' command to generate `(C)'. In a printed
870 manual, this is a `c' inside a circle, and in Info, this is `(C)'.
873 File: texinfo.info, Node: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions
875 `@pounds{}' (#): Pounds Sterling
876 ================================
878 Use the `@pounds{}' command to generate `#'. In a printed manual,
879 this is the symbol for the currency pounds sterling. In Info, it is a
880 `#'. Other currency symbols are unfortunately not available.
883 File: texinfo.info, Node: minus, Next: math, Prev: pounds, Up: Insertions
885 `@minus'{} (-): Inserting a Minus Sign
886 ======================================
888 Use the `@minus{}' command to generate a minus sign. In a
889 fixed-width font, this is a single hyphen, but in a proportional font,
890 the symbol is the customary length for a minus sign--a little longer
891 than a hyphen, shorter than an em-dash:
893 `-' is a minus sign generated with `@minus{}',
895 `-' is a hyphen generated with the character `-',
897 `---' is an em-dash for text.
899 In the fixed-width font used by Info, `@minus{}' is the same as a
902 You should not use `@minus{}' inside `@code' or `@example' because
903 the width distinction is not made in the fixed-width font they use.
905 When you use `@minus' to specify the mark beginning each entry in an
906 itemized list, you do not need to type the braces (*note `@itemize':
910 File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions
912 `@math' - Inserting Mathematical Expressions
913 ============================================
915 You can write a short mathematical expression with the `@math'
916 command. Write the mathematical expression between braces, like this:
918 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
920 This produces the following in Info:
922 (a + b)(a + b) = a^2 + 2ab + b^2
924 Thus, the `@math' command has no effect on the Info output.
926 For complex mathematical expressions, you can also use TeX directly
927 (*note Raw Formatter Commands::). When you use TeX directly, remember
928 to write the mathematical expression between one or two `$'
929 (dollar-signs) as appropriate.
932 File: texinfo.info, Node: Glyphs, Next: Images, Prev: math, Up: Insertions
937 In Texinfo, code is often illustrated in examples that are delimited
938 by `@example' and `@end example', or by `@lisp' and `@end lisp'. In
939 such examples, you can indicate the results of evaluation or an
940 expansion using `=>' or `==>'. Likewise, there are commands to insert
941 glyphs to indicate printed output, error messages, equivalence of
942 expressions, and the location of point.
944 The glyph-insertion commands do not need to be used within an
945 example, but most often they are. Every glyph-insertion command is
946 followed by a pair of left- and right-hand braces.
951 * result:: How to show the result of expression.
952 * expansion:: How to indicate an expansion.
953 * Print Glyph:: How to indicate printed output.
954 * Error Glyph:: How to indicate an error message.
955 * Equivalence:: How to indicate equivalence.
956 * Point Glyph:: How to indicate the location of point.
959 File: texinfo.info, Node: Glyphs Summary, Next: result, Prev: Glyphs, Up: Glyphs
964 Here are the different glyph commands:
967 `@result{}' points to the result of an expression.
970 `@expansion{}' shows the results of a macro expansion.
973 `@print{}' indicates printed output.
976 `@error{}' indicates that the following text is an error message.
979 `@equiv{}' indicates the exact equivalence of two forms.
982 `@point{}' shows the location of point.
994 File: texinfo.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs
996 `@result{}' (=>): Indicating Evaluation
997 ---------------------------------------
999 Use the `@result{}' command to indicate the result of evaluating an
1002 The `@result{}' command is displayed as `=>' in Info and as a double
1003 stemmed arrow in the printed output.
1005 Thus, the following,
1010 may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
1013 File: texinfo.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs
1015 `@expansion{}' (==>): Indicating an Expansion
1016 ---------------------------------------------
1018 When an expression is a macro call, it expands into a new expression.
1019 You can indicate the result of the expansion with the `@expansion{}'
1022 The `@expansion{}' command is displayed as `==>' in Info and as a
1023 long arrow with a flat base in the printed output.
1025 For example, the following
1029 @expansion{} (car (cdr (cdr '(a b c))))
1036 ==> (car (cdr (cdr '(a b c))))
1039 which may be read as:
1041 `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
1042 result of evaluating the expression is `c'.
1044 Often, as in this case, an example looks better if the `@expansion{}'
1045 and `@result{}' commands are indented five spaces.
1048 File: texinfo.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs
1050 `@print{}' (-|): Indicating Printed Output
1051 ------------------------------------------
1053 Sometimes an expression will print output during its execution. You
1054 can indicate the printed output with the `@print{}' command.
1056 The `@print{}' command is displayed as `-|' in Info and similarly, as
1057 a horizontal dash butting against a vertical bar, in the printed output.
1059 In the following example, the printed text is indicated with `-|',
1060 and the value of the expression follows on the last line.
1062 (progn (print 'foo) (print 'bar))
1067 In a Texinfo source file, this example is written as follows:
1070 (progn (print 'foo) (print 'bar))
1077 File: texinfo.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs
1079 `@error{}' (error-->): Indicating an Error Message
1080 --------------------------------------------------
1082 A piece of code may cause an error when you evaluate it. You can
1083 designate the error message with the `@error{}' command.
1085 The `@error{}' command is displayed as `error-->' in Info and as the
1086 word `error' in a box in the printed output.
1092 @error{} Wrong type argument: integer-or-marker-p, x
1098 error--> Wrong type argument: integer-or-marker-p, x
1100 This indicates that the following error message is printed when you
1101 evaluate the expression:
1103 Wrong type argument: integer-or-marker-p, x
1105 `error-->' itself is not part of the error message.
1108 File: texinfo.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs
1110 `@equiv{}' (==): Indicating Equivalence
1111 ---------------------------------------
1113 Sometimes two expressions produce identical results. You can
1114 indicate the exact equivalence of two forms with the `@equiv{}' command.
1116 The `@equiv{}' command is displayed as `==' in Info and as a three
1117 parallel horizontal lines in the printed output.
1122 (make-sparse-keymap) @equiv{} (list 'keymap)
1127 (make-sparse-keymap) == (list 'keymap)
1129 This indicates that evaluating `(make-sparse-keymap)' produces
1130 identical results to evaluating `(list 'keymap)'.
1133 File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs
1135 `@point{}' (-!-): Indicating Point in a Buffer
1136 ----------------------------------------------
1138 Sometimes you need to show an example of text in an Emacs buffer. In
1139 such examples, the convention is to include the entire contents of the
1140 buffer in question between two lines of dashes containing the buffer
1143 You can use the `@point{}' command to show the location of point in
1144 the text in the buffer. (The symbol for point, of course, is not part
1145 of the text in the buffer; it indicates the place _between_ two
1146 characters where point is located.)
1148 The `@point{}' command is displayed as `-!-' in Info and as a small
1149 five pointed star in the printed output.
1151 The following example shows the contents of buffer `foo' before and
1152 after evaluating a Lisp command to insert the word `changed'.
1154 ---------- Buffer: foo ----------
1155 This is the -!-contents of foo.
1156 ---------- Buffer: foo ----------
1160 ---------- Buffer: foo ----------
1161 This is the changed -!-contents of foo.
1162 ---------- Buffer: foo ----------
1164 In a Texinfo source file, the example is written like this:
1167 ---------- Buffer: foo ----------
1168 This is the @point{}contents of foo.
1169 ---------- Buffer: foo ----------
1173 ---------- Buffer: foo ----------
1174 This is the changed @point{}contents of foo.
1175 ---------- Buffer: foo ----------
1179 File: texinfo.info, Node: Images, Prev: Glyphs, Up: Insertions
1184 You can insert an image in an external file with the `@image' command:
1186 @image{FILENAME, [WIDTH], [HEIGHT]}
1188 The FILENAME argument is mandatory, and must not have an extension,
1189 because the different processors support different formats: TeX reads
1190 the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo'
1191 uses `FILENAME.txt' verbatim for Info output (more or less as if it was
1192 an `@example'). HTML output requires `FILENAME.jpg'.
1194 The optional WIDTH and HEIGHT arguments specify the size to scale the
1195 image to (they are ignored for Info output). If they are both
1196 specified, the image is presented in its natural size (given in the
1197 file); if only one is specified, the other is scaled proportionately;
1198 and if both are specified, both are respected, thus possibly distorting
1199 the original image by changing its aspect ratio.
1201 The WIDTH and HEIGHT may be specified using any valid TeX dimension,
1205 point (72.27pt = 1in)
1211 big point (72bp = 1in)
1217 centimeter (2.54cm = 1in)
1220 millimeter (10mm = 1cm)
1223 dido^t point (1157dd = 1238pt)
1229 scaled point (65536sp = 1pt)
1231 For example, the following will scale a file `ridt.eps' to one inch
1232 vertically, with the width scaled proportionately:
1236 For `@image' to work with TeX, the file `epsf.tex' must be installed
1237 somewhere that TeX can find it. This file is included in the Texinfo
1238 distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'.
1241 File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
1243 Making and Preventing Breaks
1244 ****************************
1246 Usually, a Texinfo file is processed both by TeX and by one of the
1247 Info formatting commands. Line, paragraph, or page breaks sometimes
1248 occur in the `wrong' place in one or other form of output. You must
1249 ensure that text looks right both in the printed manual and in the Info
1252 For example, in a printed manual, page breaks may occur awkwardly in
1253 the middle of an example; to prevent this, you can hold text together
1254 using a grouping command that keeps the text from being split across
1255 two pages. Conversely, you may want to force a page break where none
1256 would occur normally. Fortunately, problems like these do not often
1257 arise. When they do, use the break, break prevention, or pagination
1262 * Break Commands:: Cause and prevent splits.
1263 * Line Breaks:: How to force a single line to use two lines.
1264 * - and hyphenation:: How to tell TeX about hyphenation points.
1265 * w:: How to prevent unwanted line breaks.
1266 * sp:: How to insert blank lines.
1267 * page:: How to force the start of a new page.
1268 * group:: How to prevent unwanted page breaks.
1269 * need:: Another way to prevent unwanted page breaks.
1272 File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks
1277 The break commands create or allow line and paragraph breaks:
1286 Insert a discretionary hyphen.
1288 `@hyphenation{HY-PHEN-A-TED WORDS}'
1289 Define hyphen points in HY-PHEN-A-TED WORDS.
1291 The line-break-prevention command holds text together all on one line:
1294 Prevent TEXT from being split and hyphenated across two lines.
1296 The pagination commands apply only to printed output, since Info
1297 files do not have pages.
1300 Start a new page in the printed manual.
1303 Hold text together that must appear on one printed page.
1306 Start a new printed page if not enough space on this one.
1309 File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
1311 `@*': Generate Line Breaks
1312 ==========================
1314 The `@*' command forces a line break in both the printed manual and
1319 This line @* is broken @*in two places.
1327 (Note that the space after the first `@*' command is faithfully carried
1328 down to the next line.)
1330 The `@*' command is often used in a file's copyright page:
1332 This is edition 2.0 of the Texinfo documentation,@*
1335 In this case, the `@*' command keeps TeX from stretching the line
1336 across the whole page in an ugly manner.
1338 *Please note:* Do not write braces after an `@*' command; they are
1341 Do not write an `@refill' command at the end of a paragraph
1342 containing an `@*' command; it will cause the paragraph to be
1343 refilled after the line break occurs, negating the effect of the
1347 File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
1349 `@-' and `@hyphenation': Helping TeX hyphenate
1350 ==============================================
1352 Although TeX's hyphenation algorithm is generally pretty good, it
1353 does miss useful hyphenation points from time to time. (Or, far more
1354 rarely, insert an incorrect hyphenation.) So, for documents with an
1355 unusual vocabulary or when fine-tuning for a printed edition, you may
1356 wish to help TeX out. Texinfo supports two commands for this:
1359 Insert a discretionary hyphen, i.e., a place where TeX can (but
1360 does not have to) hyphenate. This is especially useful when you
1361 notice an overfull hbox is due to TeX missing a hyphenation (*note
1362 Overfull hboxes::). TeX will not insert any hyphenation points in
1363 a word containing `@-'.
1365 `@hyphenation{HY-PHEN-A-TED WORDS}'
1366 Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
1367 a `-' at each hyphenation point. For example:
1368 @hyphenation{man-u-script man-u-scripts}
1370 TeX only uses the specified hyphenation points when the words
1371 match exactly, so give all necessary variants.
1373 Info output is not hyphenated, so these commands have no effect there.
1376 File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks
1378 `@w'{TEXT}: Prevent Line Breaks
1379 ===============================
1381 `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
1383 You can use the `@w' command to prevent TeX from automatically
1384 hyphenating a long name or phrase that happens to fall near the end of a
1387 You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
1391 You can copy GNU software from `ftp.gnu.ai.mit.edu'.
1393 *Caution:* Do not write an `@refill' command at the end of a
1394 paragraph containing an `@w' command; it will cause the paragraph
1395 to be refilled and may thereby negate the effect of the `@w'
1399 File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks
1401 `@sp' N: Insert Blank Lines
1402 ===========================
1404 A line beginning with and containing only `@sp N' generates N blank
1405 lines of space in both the printed manual and the Info file. `@sp'
1406 also forces a paragraph break. For example,
1410 generates two blank lines.
1412 The `@sp' command is most often used in the title page.
1415 File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks
1417 `@page': Start a New Page
1418 =========================
1420 A line containing only `@page' starts a new page in a printed manual.
1421 The command has no effect on Info files since they are not paginated.
1422 An `@page' command is often used in the `@titlepage' section of a
1423 Texinfo file to start the copyright page.