1 This is ../info/texinfo.info, produced by makeinfo version 4.0 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 GNU Emacs Manual', *note Splitting Windows: (xemacs)Split Window.):
164 @multitable @columnfractions .15 .45 .4
165 @item Key @tab Command @tab Description
167 @tab @code{split-window-vertically}
168 @tab Split the selected window into two windows,
169 with one above the other.
171 @tab @code{split-window-horizontally}
172 @tab Split the selected window into two windows
173 positioned side by side.
176 @tab In the mode line or scroll bar of a window,
182 Key Command Description
183 C-x 2 `split-window-vertically' Split the selected window
184 into two windows, with one
186 C-x 3 `split-window-horizontally' Split the selected window
187 into two windows positioned
189 C-Mouse-2 In the mode line or scroll
190 bar of a window, split that
194 File: texinfo.info, Node: Indices, Next: Insertions, Prev: Lists and Tables, Up: Top
199 Using Texinfo, you can generate indices without having to sort and
200 collate entries manually. In an index, the entries are listed in
201 alphabetical order, together with information on how to find the
202 discussion of each entry. In a printed manual, this information
203 consists of page numbers. In an Info file, this information is a menu
204 entry leading to the first node referenced.
206 Texinfo provides several predefined kinds of index: an index for
207 functions, an index for variables, an index for concepts, and so on.
208 You can combine indices or use them for other than their canonical
209 purpose. If you wish, you can define your own indices.
213 * Index Entries:: Choose different words for index entries.
214 * Predefined Indices:: Use different indices for different kinds
216 * Indexing Commands:: How to make an index entry.
217 * Combining Indices:: How to combine indices.
218 * New Indices:: How to define your own indices.
221 File: texinfo.info, Node: Index Entries, Next: Predefined Indices, Prev: Indices, Up: Indices
226 When you are making index entries, it is good practice to think of the
227 different ways people may look for something. Different people _do
228 not_ think of the same words when they look something up. A helpful
229 index will have items indexed under all the different words that people
230 may use. For example, one reader may think it obvious that the
231 two-letter names for indices should be listed under "Indices,
232 two-letter names", since the word "Index" is the general concept. But
233 another reader may remember the specific concept of two-letter names
234 and search for the entry listed as "Two letter names for indices". A
235 good index will have both entries and will help both readers.
237 Like typesetting, the construction of an index is a highly skilled,
238 professional art, the subtleties of which are not appreciated until you
239 need to do it yourself.
241 *Note Printing Indices & Menus::, for information about printing an
242 index at the end of a book or creating an index menu in an Info file.
245 File: texinfo.info, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices
250 Texinfo provides six predefined indices:
252 * A "concept index" listing concepts that are discussed.
254 * A "function index" listing functions (such as entry points of
257 * A "variables index" listing variables (such as global variables of
260 * A "keystroke index" listing keyboard commands.
262 * A "program index" listing names of programs.
264 * A "data type index" listing data types (such as structures defined
267 Not every manual needs all of these, and most manuals use two or three
268 of them. This manual has two indices: a concept index and an @-command
269 index (that is actually the function index but is called a command
270 index in the chapter heading). Two or more indices can be combined
271 into one using the `@synindex' or `@syncodeindex' commands. *Note
275 File: texinfo.info, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices
277 Defining the Entries of an Index
278 ================================
280 The data to make an index come from many individual indexing commands
281 scattered throughout the Texinfo source file. Each command says to add
282 one entry to a particular index; after formatting, the index will give
283 the current page number or node name as the reference.
285 An index entry consists of an indexing command at the beginning of a
286 line followed, on the rest of the line, by the entry.
288 For example, this section begins with the following five entries for
291 @cindex Defining indexing entries
292 @cindex Index entries
293 @cindex Entries for an index
294 @cindex Specifying index entries
295 @cindex Creating index entries
297 Each predefined index has its own indexing command--`@cindex' for the
298 concept index, `@findex' for the function index, and so on.
300 Concept index entries consist of text. The best way to write an index
301 is to choose entries that are terse yet clear. If you can do this, the
302 index often looks better if the entries are not capitalized, but
303 written just as they would appear in the middle of a sentence.
304 (Capitalize proper names and acronyms that always call for upper case
305 letters.) This is the case convention we use in most GNU manuals'
308 If you don't see how to make an entry terse yet clear, make it longer
309 and clear--not terse and confusing. If many of the entries are several
310 words long, the index may look better if you use a different convention:
311 to capitalize the first word of each entry. But do not capitalize a
312 case-sensitive name such as a C or Lisp function name or a shell
313 command; that would be a spelling error.
315 Whichever case convention you use, please use it consistently!
317 Entries in indices other than the concept index are symbol names in
318 programming languages, or program names; these names are usually
319 case-sensitive, so use upper and lower case as required for them.
321 By default, entries for a concept index are printed in a small roman
322 font and entries for the other indices are printed in a small `@code'
323 font. You may change the way part of an entry is printed with the
324 usual Texinfo commands, such as `@file' for file names and `@emph' for
325 emphasis (*note Marking Text::).
327 The six indexing commands for predefined indices are:
330 Make an entry in the concept index for CONCEPT.
333 Make an entry in the function index for FUNCTION.
336 Make an entry in the variable index for VARIABLE.
339 Make an entry in the key index for KEYSTROKE.
342 Make an entry in the program index for PROGRAM.
345 Make an entry in the data type index for DATA TYPE.
347 *Caution:* Do not use a colon in an index entry. In Info, a colon
348 separates the menu entry name from the node name. An extra colon
349 confuses Info. *Note The Parts of a Menu: Menu Parts, for more
350 information about the structure of a menu entry.
352 If you write several identical index entries in different places in a
353 Texinfo file, the index in the printed manual will list all the pages to
354 which those entries refer. However, the index in the Info file will
355 list *only* the node that references the *first* of those index
356 entries. Therefore, it is best to write indices in which each entry
357 refers to only one place in the Texinfo file. Fortunately, this
358 constraint is a feature rather than a loss since it means that the index
359 will be easy to use. Otherwise, you could create an index that lists
360 several pages for one entry and your reader would not know to which page
361 to turn. If you have two identical entries for one topic, change the
362 topics slightly, or qualify them to indicate the difference.
364 You are not actually required to use the predefined indices for their
365 canonical purposes. For example, suppose you wish to index some C
366 preprocessor macros. You could put them in the function index along
367 with actual functions, just by writing `@findex' commands for them;
368 then, when you print the "Function Index" as an unnumbered chapter, you
369 could give it the title `Function and Macro Index' and all will be
370 consistent for the reader. Or you could put the macros in with the
371 data types by writing `@tindex' commands for them, and give that index
372 a suitable title so the reader will understand. (*Note Printing
376 File: texinfo.info, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices
381 Sometimes you will want to combine two disparate indices such as
382 functions and concepts, perhaps because you have few enough of one of
383 them that a separate index for them would look silly.
385 You could put functions into the concept index by writing `@cindex'
386 commands for them instead of `@findex' commands, and produce a
387 consistent manual by printing the concept index with the title
388 `Function and Concept Index' and not printing the `Function Index' at
389 all; but this is not a robust procedure. It works only if your
390 document is never included as part of another document that is designed
391 to have a separate function index; if your document were to be included
392 with such a document, the functions from your document and those from
393 the other would not end up together. Also, to make your function names
394 appear in the right font in the concept index, you would need to
395 enclose every one of them between the braces of `@code'.
399 * syncodeindex:: How to merge two indices, using `@code'
400 font for the merged-from index.
401 * synindex:: How to merge two indices, using the
402 default font of the merged-to index.
405 File: texinfo.info, Node: syncodeindex, Next: synindex, Prev: Combining Indices, Up: Combining Indices
410 When you want to combine functions and concepts into one index, you
411 should index the functions with `@findex' and index the concepts with
412 `@cindex', and use the `@syncodeindex' command to redirect the function
413 index entries into the concept index.
415 The `@syncodeindex' command takes two arguments; they are the name of
416 the index to redirect, and the name of the index to redirect it to.
417 The template looks like this:
419 @syncodeindex FROM TO
421 For this purpose, the indices are given two-letter names:
441 Write an `@syncodeindex' command before or shortly after the
442 end-of-header line at the beginning of a Texinfo file. For example, to
443 merge a function index with a concept index, write the following:
447 This will cause all entries designated for the function index to merge
448 in with the concept index instead.
450 To merge both a variables index and a function index into a concept
451 index, write the following:
456 The `@syncodeindex' command puts all the entries from the `from'
457 index (the redirected index) into the `@code' font, overriding whatever
458 default font is used by the index to which the entries are now
459 directed. This way, if you direct function names from a function index
460 into a concept index, all the function names are printed in the `@code'
461 font as you would expect.
464 File: texinfo.info, Node: synindex, Prev: syncodeindex, Up: Combining Indices
469 The `@synindex' command is nearly the same as the `@syncodeindex'
470 command, except that it does not put the `from' index entries into the
471 `@code' font; rather it puts them in the roman font. Thus, you use
472 `@synindex' when you merge a concept index into a function index.
474 *Note Printing Indices & Menus::, for information about printing an
475 index at the end of a book or creating an index menu in an Info file.
478 File: texinfo.info, Node: New Indices, Prev: Combining Indices, Up: Indices
483 In addition to the predefined indices, you may use the `@defindex'
484 and `@defcodeindex' commands to define new indices. These commands
485 create new indexing @-commands with which you mark index entries. The
486 `@defindex 'command is used like this:
490 The name of an index should be a two letter word, such as `au'. For
495 This defines a new index, called the `au' index. At the same time,
496 it creates a new indexing command, `@auindex', that you can use to make
497 index entries. Use the new indexing command just as you would use a
498 predefined indexing command.
500 For example, here is a section heading followed by a concept index
501 entry and two `au' index entries.
503 @section Cognitive Semantics
504 @cindex kinesthetic image schemas
505 @auindex Johnson, Mark
506 @auindex Lakoff, George
508 (Evidently, `au' serves here as an abbreviation for "author".) Texinfo
509 constructs the new indexing command by concatenating the name of the
510 index with `index'; thus, defining an `au' index leads to the automatic
511 creation of an `@auindex' command.
513 Use the `@printindex' command to print the index, as you do with the
514 predefined indices. For example:
516 @node Author Index, Subject Index, , Top
517 @unnumbered Author Index
521 The `@defcodeindex' is like the `@defindex' command, except that, in
522 the printed output, it prints entries in an `@code' font instead of a
523 roman font. Thus, it parallels the `@findex' command rather than the
526 You should define new indices within or right after the end-of-header
527 line of a Texinfo file, before any `@synindex' or `@syncodeindex'
528 commands (*note Header::).
531 File: texinfo.info, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top
536 Texinfo provides several commands for inserting characters that have
537 special meaning in Texinfo, such as braces, and for other graphic
538 elements that do not correspond to simple characters you can type.
542 * Braces Atsigns:: How to insert braces, `@'.
543 * Inserting Space:: How to insert the right amount of space
545 * Inserting Accents:: How to insert accents and special characters.
546 * Dots Bullets:: How to insert dots and bullets.
547 * TeX and copyright:: How to insert the TeX logo
548 and the copyright symbol.
549 * pounds:: How to insert the pounds currency symbol.
550 * minus:: How to insert a minus sign.
551 * math:: How to format a mathematical expression.
552 * Glyphs:: How to indicate results of evaluation,
553 expansion of macros, errors, etc.
554 * Images:: How to include graphics.
557 File: texinfo.info, Node: Braces Atsigns, Next: Inserting Space, Prev: Insertions, Up: Insertions
559 Inserting @ and Braces
560 ======================
562 `@' and curly braces are special characters in Texinfo. To insert
563 these characters so they appear in text, you must put an `@' in front
564 of these characters to prevent Texinfo from misinterpreting them.
566 Do not put braces after any of these commands; they are not necessary.
570 * Inserting An Atsign:: How to insert `@'.
571 * Inserting Braces:: How to insert `{' and `}'.
574 File: texinfo.info, Node: Inserting An Atsign, Next: Inserting Braces, Prev: Braces Atsigns, Up: Braces Atsigns
576 Inserting `@' with @@
577 ---------------------
579 `@@' stands for a single `@' in either printed or Info output.
581 Do not put braces after an `@@' command.
584 File: texinfo.info, Node: Inserting Braces, Prev: Inserting An Atsign, Up: Braces Atsigns
586 Inserting `{' and `}'with @{ and @}
587 -----------------------------------
589 `@{' stands for a single `{' in either printed or Info output.
591 `@}' stands for a single `}' in either printed or Info output.
593 Do not put braces after either an `@{' or an `@}' command.
596 File: texinfo.info, Node: Inserting Space, Next: Inserting Accents, Prev: Braces Atsigns, Up: Insertions
601 The following sections describe commands that control spacing of
602 various kinds within and after sentences.
606 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
607 * Ending a Sentence:: Sometimes it does.
608 * Multiple Spaces:: Inserting multiple spaces.
609 * dmn:: How to format a dimension.
612 File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Inserting Space, Up: Inserting Space
614 Not Ending a Sentence
615 ---------------------
617 Depending on whether a period or exclamation point or question mark is
618 inside or at the end of a sentence, less or more space is inserted after
619 a period in a typeset manual. Since it is not always possible for
620 Texinfo to determine when a period ends a sentence and when it is used
621 in an abbreviation, special commands are needed in some circumstances.
622 (Usually, Texinfo can guess how to handle periods, so you do not need to
623 use the special commands; you just enter a period as you would if you
624 were using a typewriter, which means you put two spaces after the
625 period, question mark, or exclamation mark that ends a sentence.)
627 Use the `@:' command after a period, question mark, exclamation mark,
628 or colon that should not be followed by extra space. For example, use
629 `@:' after periods that end abbreviations which are not at the ends of
634 The s.o.p.@: has three parts ...
635 The s.o.p. has three parts ...
639 The s.o.p. has three parts ...
640 The s.o.p. has three parts ...
642 (Incidentally, `s.o.p.' is an abbreviation for "Standard Operating
645 `@:' has no effect on the Info output. Do not put braces after `@:'.
648 File: texinfo.info, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space
653 Use `@.' instead of a period, `@!' instead of an exclamation point,
654 and `@?' instead of a question mark at the end of a sentence that ends
655 with a single capital letter. Otherwise, TeX will think the letter is
656 an abbreviation and will not insert the correct end-of-sentence
657 spacing. Here is an example:
659 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.
660 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
664 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.
667 In the Info file output, `@.' is equivalent to a simple `.'; likewise
670 The meanings of `@:' and `@.' in Texinfo are designed to work well
671 with the Emacs sentence motion commands (*note Sentences:
672 (xemacs)Sentences.). This made it necessary for them to be
673 incompatible with some other formatting systems that use @-commands.
675 Do not put braces after any of these commands.
678 File: texinfo.info, Node: Multiple Spaces, Next: dmn, Prev: Ending a Sentence, Up: Inserting Space
683 Ordinarily, TeX collapses multiple whitespace characters (space, tab,
684 and newline) into a single space. Info output, on the other hand,
685 preserves whitespace as you type it, except for changing a newline into
686 a space; this is why it is important to put two spaces at the end of
687 sentences in Texinfo documents.
689 Occasionally, you may want to actually insert several consecutive
690 spaces, either for purposes of example (what your program does with
691 multiple spaces as input), or merely for purposes of appearance in
692 headings or lists. Texinfo supports three commands: `@SPACE', `@TAB',
693 and `@NL', all of which insert a single space into the output. (Here,
694 `@SPACE' represents an `@' character followed by a space, i.e., `@ ',
695 and `TAB' and `NL' represent the tab character and end-of-line, i.e.,
696 when `@' is the last character on a line.)
706 Other possible uses of `@SPACE' have been subsumed by `@multitable'
707 (*note Multi-column Tables::).
709 Do not follow any of these commands with braces.
712 File: texinfo.info, Node: dmn, Prev: Multiple Spaces, Up: Inserting Space
714 `@dmn'{DIMENSION}: Format a Dimension
715 -------------------------------------
717 At times, you may want to write `12pt' or `8.5in' with little or no
718 space between the number and the abbreviation for the dimension. You
719 can use the `@dmn' command to do this. On seeing the command, TeX
720 inserts just enough space for proper typesetting; the Info formatting
721 commands insert no space at all, since the Info file does not require
724 To use the `@dmn' command, write the number and then follow it
725 immediately, with no intervening space, by `@dmn', and then by the
726 dimension within braces. For example,
728 A4 paper is 8.27@dmn{in} wide.
732 A4 paper is 8.27in wide.
734 Not everyone uses this style. Some people prefer `8.27 in.@:' or
735 `8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases,
736 however, the formatters may insert a line break between the number and
737 the dimension, so use `@w' (*note w::). Also, if you write a period
738 after an abbreviation within a sentence, you should write `@:' after
739 the period to prevent TeX from inserting extra whitespace, as shown
740 here. *Note Inserting Space::.
743 File: texinfo.info, Node: Inserting Accents, Next: Dots Bullets, Prev: Inserting Space, Up: Insertions
748 Here is a table with the commands Texinfo provides for inserting
749 floating accents. The commands with non-alphabetic names do not take
750 braces around their argument (which is taken to be the next character).
751 (Exception: `@,' _does_ take braces around its argument.) This is so
752 as to make the source as convenient to type and read as possible, since
753 accented characters are very common in some languages.
758 @,{c} c, cedilla accent
759 @=o o= macron/overbar accent
760 @^o o^ circumflex accent
763 @dotaccent{o} o. overdot accent
764 @H{o} o'' long Hungarian umlaut
765 @ringaccent{o} o* ring accent
766 @tieaccent{oo} oo[ tie-after accent
767 @u{o} o( breve accent
768 @ubaraccent{o} o_ underbar accent
769 @udotaccent{o} .o underdot accent
770 @v{o} o< hacek or check accent
772 This table lists the Texinfo commands for inserting other characters
773 commonly used in languages other than English.
775 @exclamdown{} ! upside-down !
776 @questiondown{} ? upside-down ?
777 @aa{},@AA{} aa,AA A,a with circle
778 @ae{},@AE{} ae,AE ae,AE ligatures
779 @dotless{i} i dotless i
780 @dotless{j} j dotless j
781 @l{},@L{} /l,/L suppressed-L,l
782 @o{},@O{} /o,/O O,o with slash
783 @oe{},@OE{} oe,OE OE,oe ligatures
784 @ss{} ss es-zet or sharp S
787 File: texinfo.info, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Accents, Up: Insertions
789 Inserting Ellipsis, Dots, and Bullets
790 =====================================
792 An "ellipsis" (a line of dots) is not typeset as a string of periods,
793 so a special command is used for ellipsis in Texinfo. The `@bullet'
794 command is special, too. Each of these commands is followed by a pair
795 of braces, `{}', without any whitespace between the name of the command
796 and the braces. (You need to use braces with these commands because
797 you can use them next to other text; without the braces, the formatters
798 would be confused. *Note @-Command Syntax: Command Syntax, for further
803 * dots:: How to insert dots ...
804 * bullet:: How to insert a bullet.
807 File: texinfo.info, Node: dots, Next: bullet, Prev: Dots Bullets, Up: Dots Bullets
812 Use the `@dots{}' command to generate an ellipsis, which is three
813 dots in a row, appropriately spaced, like this: `...'. Do not simply
814 write three periods in the input file; that would work for the Info
815 file output, but would produce the wrong amount of space between the
816 periods in the printed manual.
818 Similarly, the `@enddots{}' command generates an end-of-sentence
819 ellipsis (four dots) ....
822 File: texinfo.info, Node: bullet, Prev: dots, Up: Dots Bullets
827 Use the `@bullet{}' command to generate a large round dot, or the
828 closest possible thing to one. In Info, an asterisk is used.
832 When you use `@bullet' in `@itemize', you do not need to type the
833 braces, because `@itemize' supplies them. (*Note `@itemize': itemize.)
836 File: texinfo.info, Node: TeX and copyright, Next: pounds, Prev: Dots Bullets, Up: Insertions
838 Inserting TeX and the Copyright Symbol
839 ======================================
841 The logo `TeX' is typeset in a special fashion and it needs an
842 @-command. The copyright symbol, `(C)', is also special. Each of
843 these commands is followed by a pair of braces, `{}', without any
844 whitespace between the name of the command and the braces.
848 * tex:: How to insert the TeX logo.
849 * copyright symbol:: How to use `@copyright'{}.
852 File: texinfo.info, Node: tex, Next: copyright symbol, Prev: TeX and copyright, Up: TeX and copyright
857 Use the `@TeX{}' command to generate `TeX'. In a printed manual,
858 this is a special logo that is different from three ordinary letters.
859 In Info, it just looks like `TeX'. The `@TeX{}' command is unique
860 among Texinfo commands in that the `T' and the `X' are in upper case.
863 File: texinfo.info, Node: copyright symbol, Prev: tex, Up: TeX and copyright
868 Use the `@copyright{}' command to generate `(C)'. In a printed
869 manual, this is a `c' inside a circle, and in Info, this is `(C)'.
872 File: texinfo.info, Node: pounds, Next: minus, Prev: TeX and copyright, Up: Insertions
874 `@pounds{}' (#): Pounds Sterling
875 ================================
877 Use the `@pounds{}' command to generate `#'. In a printed manual,
878 this is the symbol for the currency pounds sterling. In Info, it is a
879 `#'. Other currency symbols are unfortunately not available.
882 File: texinfo.info, Node: minus, Next: math, Prev: pounds, Up: Insertions
884 `@minus'{} (-): Inserting a Minus Sign
885 ======================================
887 Use the `@minus{}' command to generate a minus sign. In a
888 fixed-width font, this is a single hyphen, but in a proportional font,
889 the symbol is the customary length for a minus sign--a little longer
890 than a hyphen, shorter than an em-dash:
892 `-' is a minus sign generated with `@minus{}',
894 `-' is a hyphen generated with the character `-',
896 `---' is an em-dash for text.
898 In the fixed-width font used by Info, `@minus{}' is the same as a
901 You should not use `@minus{}' inside `@code' or `@example' because
902 the width distinction is not made in the fixed-width font they use.
904 When you use `@minus' to specify the mark beginning each entry in an
905 itemized list, you do not need to type the braces (*note `@itemize':
909 File: texinfo.info, Node: math, Next: Glyphs, Prev: minus, Up: Insertions
911 `@math' - Inserting Mathematical Expressions
912 ============================================
914 You can write a short mathematical expression with the `@math'
915 command. Write the mathematical expression between braces, like this:
917 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
919 This produces the following in Info:
921 (a + b)(a + b) = a^2 + 2ab + b^2
923 Thus, the `@math' command has no effect on the Info output.
925 For complex mathematical expressions, you can also use TeX directly
926 (*note Raw Formatter Commands::). When you use TeX directly, remember
927 to write the mathematical expression between one or two `$'
928 (dollar-signs) as appropriate.
931 File: texinfo.info, Node: Glyphs, Next: Images, Prev: math, Up: Insertions
936 In Texinfo, code is often illustrated in examples that are delimited
937 by `@example' and `@end example', or by `@lisp' and `@end lisp'. In
938 such examples, you can indicate the results of evaluation or an
939 expansion using `=>' or `==>'. Likewise, there are commands to insert
940 glyphs to indicate printed output, error messages, equivalence of
941 expressions, and the location of point.
943 The glyph-insertion commands do not need to be used within an
944 example, but most often they are. Every glyph-insertion command is
945 followed by a pair of left- and right-hand braces.
950 * result:: How to show the result of expression.
951 * expansion:: How to indicate an expansion.
952 * Print Glyph:: How to indicate printed output.
953 * Error Glyph:: How to indicate an error message.
954 * Equivalence:: How to indicate equivalence.
955 * Point Glyph:: How to indicate the location of point.
958 File: texinfo.info, Node: Glyphs Summary, Next: result, Prev: Glyphs, Up: Glyphs
963 Here are the different glyph commands:
966 `@result{}' points to the result of an expression.
969 `@expansion{}' shows the results of a macro expansion.
972 `@print{}' indicates printed output.
975 `@error{}' indicates that the following text is an error message.
978 `@equiv{}' indicates the exact equivalence of two forms.
981 `@point{}' shows the location of point.
993 File: texinfo.info, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs
995 `@result{}' (=>): Indicating Evaluation
996 ---------------------------------------
998 Use the `@result{}' command to indicate the result of evaluating an
1001 The `@result{}' command is displayed as `=>' in Info and as a double
1002 stemmed arrow in the printed output.
1004 Thus, the following,
1009 may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".
1012 File: texinfo.info, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs
1014 `@expansion{}' (==>): Indicating an Expansion
1015 ---------------------------------------------
1017 When an expression is a macro call, it expands into a new expression.
1018 You can indicate the result of the expansion with the `@expansion{}'
1021 The `@expansion{}' command is displayed as `==>' in Info and as a
1022 long arrow with a flat base in the printed output.
1024 For example, the following
1028 @expansion{} (car (cdr (cdr '(a b c))))
1035 ==> (car (cdr (cdr '(a b c))))
1038 which may be read as:
1040 `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the
1041 result of evaluating the expression is `c'.
1043 Often, as in this case, an example looks better if the `@expansion{}'
1044 and `@result{}' commands are indented five spaces.
1047 File: texinfo.info, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs
1049 `@print{}' (-|): Indicating Printed Output
1050 ------------------------------------------
1052 Sometimes an expression will print output during its execution. You
1053 can indicate the printed output with the `@print{}' command.
1055 The `@print{}' command is displayed as `-|' in Info and similarly, as
1056 a horizontal dash butting against a vertical bar, in the printed output.
1058 In the following example, the printed text is indicated with `-|',
1059 and the value of the expression follows on the last line.
1061 (progn (print 'foo) (print 'bar))
1066 In a Texinfo source file, this example is written as follows:
1069 (progn (print 'foo) (print 'bar))
1076 File: texinfo.info, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs
1078 `@error{}' (error-->): Indicating an Error Message
1079 --------------------------------------------------
1081 A piece of code may cause an error when you evaluate it. You can
1082 designate the error message with the `@error{}' command.
1084 The `@error{}' command is displayed as `error-->' in Info and as the
1085 word `error' in a box in the printed output.
1091 @error{} Wrong type argument: integer-or-marker-p, x
1097 error--> Wrong type argument: integer-or-marker-p, x
1099 This indicates that the following error message is printed when you
1100 evaluate the expression:
1102 Wrong type argument: integer-or-marker-p, x
1104 `error-->' itself is not part of the error message.
1107 File: texinfo.info, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs
1109 `@equiv{}' (==): Indicating Equivalence
1110 ---------------------------------------
1112 Sometimes two expressions produce identical results. You can
1113 indicate the exact equivalence of two forms with the `@equiv{}' command.
1115 The `@equiv{}' command is displayed as `==' in Info and as a three
1116 parallel horizontal lines in the printed output.
1121 (make-sparse-keymap) @equiv{} (list 'keymap)
1126 (make-sparse-keymap) == (list 'keymap)
1128 This indicates that evaluating `(make-sparse-keymap)' produces
1129 identical results to evaluating `(list 'keymap)'.
1132 File: texinfo.info, Node: Point Glyph, Prev: Equivalence, Up: Glyphs
1134 `@point{}' (-!-): Indicating Point in a Buffer
1135 ----------------------------------------------
1137 Sometimes you need to show an example of text in an Emacs buffer. In
1138 such examples, the convention is to include the entire contents of the
1139 buffer in question between two lines of dashes containing the buffer
1142 You can use the `@point{}' command to show the location of point in
1143 the text in the buffer. (The symbol for point, of course, is not part
1144 of the text in the buffer; it indicates the place _between_ two
1145 characters where point is located.)
1147 The `@point{}' command is displayed as `-!-' in Info and as a small
1148 five pointed star in the printed output.
1150 The following example shows the contents of buffer `foo' before and
1151 after evaluating a Lisp command to insert the word `changed'.
1153 ---------- Buffer: foo ----------
1154 This is the -!-contents of foo.
1155 ---------- Buffer: foo ----------
1159 ---------- Buffer: foo ----------
1160 This is the changed -!-contents of foo.
1161 ---------- Buffer: foo ----------
1163 In a Texinfo source file, the example is written like this:
1166 ---------- Buffer: foo ----------
1167 This is the @point{}contents of foo.
1168 ---------- Buffer: foo ----------
1172 ---------- Buffer: foo ----------
1173 This is the changed @point{}contents of foo.
1174 ---------- Buffer: foo ----------
1178 File: texinfo.info, Node: Images, Prev: Glyphs, Up: Insertions
1183 You can insert an image in an external file with the `@image' command:
1185 @image{FILENAME, [WIDTH], [HEIGHT]}
1187 The FILENAME argument is mandatory, and must not have an extension,
1188 because the different processors support different formats: TeX reads
1189 the file `FILENAME.eps' (Encapsulated PostScript format); `makeinfo'
1190 uses `FILENAME.txt' verbatim for Info output (more or less as if it was
1191 an `@example'). HTML output requires `FILENAME.jpg'.
1193 The optional WIDTH and HEIGHT arguments specify the size to scale the
1194 image to (they are ignored for Info output). If they are both
1195 specified, the image is presented in its natural size (given in the
1196 file); if only one is specified, the other is scaled proportionately;
1197 and if both are specified, both are respected, thus possibly distorting
1198 the original image by changing its aspect ratio.
1200 The WIDTH and HEIGHT may be specified using any valid TeX dimension,
1204 point (72.27pt = 1in)
1210 big point (72bp = 1in)
1216 centimeter (2.54cm = 1in)
1219 millimeter (10mm = 1cm)
1222 dido^t point (1157dd = 1238pt)
1228 scaled point (65536sp = 1pt)
1230 For example, the following will scale a file `ridt.eps' to one inch
1231 vertically, with the width scaled proportionately:
1235 For `@image' to work with TeX, the file `epsf.tex' must be installed
1236 somewhere that TeX can find it. This file is included in the Texinfo
1237 distribution and is available from `ftp://ftp.tug.org/tex/epsf.tex'.
1240 File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top
1242 Making and Preventing Breaks
1243 ****************************
1245 Usually, a Texinfo file is processed both by TeX and by one of the
1246 Info formatting commands. Line, paragraph, or page breaks sometimes
1247 occur in the `wrong' place in one or other form of output. You must
1248 ensure that text looks right both in the printed manual and in the Info
1251 For example, in a printed manual, page breaks may occur awkwardly in
1252 the middle of an example; to prevent this, you can hold text together
1253 using a grouping command that keeps the text from being split across
1254 two pages. Conversely, you may want to force a page break where none
1255 would occur normally. Fortunately, problems like these do not often
1256 arise. When they do, use the break, break prevention, or pagination
1261 * Break Commands:: Cause and prevent splits.
1262 * Line Breaks:: How to force a single line to use two lines.
1263 * - and hyphenation:: How to tell TeX about hyphenation points.
1264 * w:: How to prevent unwanted line breaks.
1265 * sp:: How to insert blank lines.
1266 * page:: How to force the start of a new page.
1267 * group:: How to prevent unwanted page breaks.
1268 * need:: Another way to prevent unwanted page breaks.
1271 File: texinfo.info, Node: Break Commands, Next: Line Breaks, Prev: Breaks, Up: Breaks
1276 The break commands create or allow line and paragraph breaks:
1285 Insert a discretionary hyphen.
1287 `@hyphenation{HY-PHEN-A-TED WORDS}'
1288 Define hyphen points in HY-PHEN-A-TED WORDS.
1290 The line-break-prevention command holds text together all on one line:
1293 Prevent TEXT from being split and hyphenated across two lines.
1295 The pagination commands apply only to printed output, since Info
1296 files do not have pages.
1299 Start a new page in the printed manual.
1302 Hold text together that must appear on one printed page.
1305 Start a new printed page if not enough space on this one.
1308 File: texinfo.info, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks
1310 `@*': Generate Line Breaks
1311 ==========================
1313 The `@*' command forces a line break in both the printed manual and
1318 This line @* is broken @*in two places.
1326 (Note that the space after the first `@*' command is faithfully carried
1327 down to the next line.)
1329 The `@*' command is often used in a file's copyright page:
1331 This is edition 2.0 of the Texinfo documentation,@*
1334 In this case, the `@*' command keeps TeX from stretching the line
1335 across the whole page in an ugly manner.
1337 *Please note:* Do not write braces after an `@*' command; they are
1340 Do not write an `@refill' command at the end of a paragraph
1341 containing an `@*' command; it will cause the paragraph to be
1342 refilled after the line break occurs, negating the effect of the
1346 File: texinfo.info, Node: - and hyphenation, Next: w, Prev: Line Breaks, Up: Breaks
1348 `@-' and `@hyphenation': Helping TeX hyphenate
1349 ==============================================
1351 Although TeX's hyphenation algorithm is generally pretty good, it
1352 does miss useful hyphenation points from time to time. (Or, far more
1353 rarely, insert an incorrect hyphenation.) So, for documents with an
1354 unusual vocabulary or when fine-tuning for a printed edition, you may
1355 wish to help TeX out. Texinfo supports two commands for this:
1358 Insert a discretionary hyphen, i.e., a place where TeX can (but
1359 does not have to) hyphenate. This is especially useful when you
1360 notice an overfull hbox is due to TeX missing a hyphenation (*note
1361 Overfull hboxes::). TeX will not insert any hyphenation points in
1362 a word containing `@-'.
1364 `@hyphenation{HY-PHEN-A-TED WORDS}'
1365 Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put
1366 a `-' at each hyphenation point. For example:
1367 @hyphenation{man-u-script man-u-scripts}
1369 TeX only uses the specified hyphenation points when the words
1370 match exactly, so give all necessary variants.
1372 Info output is not hyphenated, so these commands have no effect there.
1375 File: texinfo.info, Node: w, Next: sp, Prev: - and hyphenation, Up: Breaks
1377 `@w'{TEXT}: Prevent Line Breaks
1378 ===============================
1380 `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT.
1382 You can use the `@w' command to prevent TeX from automatically
1383 hyphenating a long name or phrase that happens to fall near the end of a
1386 You can copy GNU software from @w{@samp{ftp.gnu.ai.mit.edu}}.
1390 You can copy GNU software from `ftp.gnu.ai.mit.edu'.
1392 *Caution:* Do not write an `@refill' command at the end of a
1393 paragraph containing an `@w' command; it will cause the paragraph
1394 to be refilled and may thereby negate the effect of the `@w'
1398 File: texinfo.info, Node: sp, Next: page, Prev: w, Up: Breaks
1400 `@sp' N: Insert Blank Lines
1401 ===========================
1403 A line beginning with and containing only `@sp N' generates N blank
1404 lines of space in both the printed manual and the Info file. `@sp'
1405 also forces a paragraph break. For example,
1409 generates two blank lines.
1411 The `@sp' command is most often used in the title page.
1414 File: texinfo.info, Node: page, Next: group, Prev: sp, Up: Breaks
1416 `@page': Start a New Page
1417 =========================
1419 A line containing only `@page' starts a new page in a printed manual.
1420 The command has no effect on Info files since they are not paginated.
1421 An `@page' command is often used in the `@titlepage' section of a
1422 Texinfo file to start the copyright page.