This is texinfo, produced by makeinfo version 4.13 from /builds/hudson/workspace/nightly-update/build/i386/components/texinfo/texinfo-4.13/doc/texinfo.txi. This manual is for GNU Texinfo (version 4.13, 18 September 2008), a documentation system that can produce both online information and a printed manual from a single source. Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License." (a) The FSF's Back-Cover Text is: "You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom." INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Update info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. * texi2pdf: (texinfo)PDF Output. PDF output for Texinfo. * pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo. * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. END-INFO-DIR-ENTRY  File: texinfo, Node: Image Scaling, Prev: Image Syntax, Up: Images 12.2.2 Image Scaling -------------------- The optional WIDTH and HEIGHT arguments to the `@image' command (see the previous section) specify the size to scale the image to. They are ignored for Info output. If neither is specified, the image is presented in its natural size (given in the file); if only one is specified, the other is scaled proportionately; and if both are specified, both are respected, thus possibly distorting the original image by changing its aspect ratio. The WIDTH and HEIGHT may be specified using any valid TeX dimension, namely: pt point (72.27pt = 1in) pc pica (1pc = 12pt) bp big point (72bp = 1in) in inch cm centimeter (2.54cm = 1in) mm millimeter (10mm = 1cm) dd dido^t point (1157dd = 1238pt) cc cicero (1cc = 12dd) sp scaled point (65536sp = 1pt) For example, the following will scale a file `ridt.eps' to one inch vertically, with the width scaled proportionately: @image{ridt,,1in} For `@image' to work with TeX, the file `epsf.tex' must be installed somewhere that TeX can find it. (The standard location is `TEXMF/tex/generic/dvips/epsf.tex', where TEXMF is a root of your TeX directory tree.) This file is included in the Texinfo distribution and is also available from `ftp://tug.org/tex/epsf.tex', among other places. `@image' can be used within a line as well as for displayed figures. Therefore, if you intend it to be displayed, be sure to leave a blank line before the command, or the output will run into the preceding text. Image scaling is presently implemented only in TeX, not in HTML or any other sort of output.  File: texinfo, Node: Footnotes, Prev: Images, Up: Special Displays 12.3 Footnotes ============== A "footnote" is for a reference that documents or elucidates the primary text.(1) Footnotes are distracting; use them sparingly, if at all. Standard bibliographical references are better placed in a bibliography at the end of a document than in footnotes throughout. * Menu: * Footnote Commands:: How to write a footnote in Texinfo. * Footnote Styles:: Controlling how footnotes appear in Info. ---------- Footnotes ---------- (1) A footnote should complement or expand upon the primary text, but a reader should not need to read a footnote to understand the primary text. For a thorough discussion of footnotes, see `The Chicago Manual of Style', which is published by the University of Chicago Press.  File: texinfo, Node: Footnote Commands, Next: Footnote Styles, Up: Footnotes 12.3.1 Footnote Commands ------------------------ In Texinfo, footnotes are created with the `@footnote' command. This command is followed immediately by a left brace, then by the text of the footnote, and then by a terminating right brace. Footnotes may be of any length (they will be broken across pages if necessary), but are usually short. The template is: ordinary text@footnote{TEXT OF FOOTNOTE} As shown here, the `@footnote' command should come right after the text being footnoted, with no intervening space; otherwise, the footnote marker might end up starting a line. For example, this clause is followed by a sample footnote(1); in the Texinfo source, it looks like this: ...a sample footnote@footnote{Here is the sample footnote.}; in the Texinfo source... As you can see, the source includes two punctuation marks next to each other; in this case, `.};' is the sequence. This is normal (the first ends the footnote and the second belongs to the sentence being footnoted), so don't worry that it looks odd. In a printed manual or book, the reference mark for a footnote is a small, superscripted number; the text of the footnote appears at the bottom of the page, below a horizontal line. In Info, the reference mark for a footnote is a pair of parentheses with the footnote number between them, like this: `(1)'. The reference mark is followed by a cross-reference link to the footnote's text. In the HTML output, footnote references are marked with a small, superscripted number which is rendered as a hypertext link to the footnote text. By the way, footnotes in the argument of an `@item' command for a `@table' must be on the same line as the `@item' (as usual). *Note Two-column Tables::. ---------- Footnotes ---------- (1) Here is the sample footnote.  File: texinfo, Node: Footnote Styles, Prev: Footnote Commands, Up: Footnotes 12.3.2 Footnote Styles ---------------------- Info has two footnote styles, which determine where the text of the footnote is located: * In the `End' node style, all the footnotes for a single node are placed at the end of that node. The footnotes are separated from the rest of the node by a line of dashes with the word `Footnotes' within it. Each footnote begins with an `(N)' reference mark. Here is an example of a single footnote in the end of node style: --------- Footnotes --------- (1) Here is a sample footnote. * In the `Separate' node style, all the footnotes for a single node are placed in an automatically constructed node of their own. In this style, a "footnote reference" follows each `(N)' reference mark in the body of the node. The footnote reference is actually a cross reference which you use to reach the footnote node. The name of the node with the footnotes is constructed by appending `-Footnotes' to the name of the node that contains the footnotes. (Consequently, the footnotes' node for the `Footnotes' node is `Footnotes-Footnotes'!) The footnotes' node has an `Up' node pointer that leads back to its parent node. Here is how the first footnote in this manual looks after being formatted for Info in the separate node style: File: texinfo.info Node: Overview-Footnotes, Up: Overview (1) The first syllable of "Texinfo" is pronounced like "speck", not "hex". ... Unless your document has long and important footnotes (as in, say, Gibbon's `Decline and Fall ...'), we recommend the `end' style, as it is simpler for readers to follow. Use the `@footnotestyle' command to specify an Info file's footnote style. Write this command at the beginning of a line followed by an argument, either `end' for the end node style or `separate' for the separate node style. For example, @footnotestyle end or @footnotestyle separate Write an `@footnotestyle' command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you include the `@footnotestyle' command between the start-of-header and end-of-header lines, the region formatting commands will format footnotes as specified.) If you do not specify a footnote style, the formatting commands use their default style. Currently, `texinfo-format-buffer' and `texinfo-format-region' use the `separate' style and `makeinfo' uses the `end' style.  File: texinfo, Node: Indices, Next: Insertions, Prev: Special Displays, Up: Top 13 Indices ********** Using Texinfo, you can generate indices without having to sort and collate entries manually. In an index, the entries are listed in alphabetical order, together with information on how to find the discussion of each entry. In a printed manual, this information consists of page numbers. In an Info file, this information is a menu entry leading to the first node referenced. Texinfo provides several predefined kinds of index: an index for functions, an index for variables, an index for concepts, and so on. You can combine indices or use them for other than their canonical purpose. Lastly, you can define your own new indices. *Note Printing Indices & Menus::, for information on how to print indices. * Menu: * Index Entries:: Choose different words for index entries. * Predefined Indices:: Use different indices for different kinds of entries. * Indexing Commands:: How to make an index entry. * Combining Indices:: How to combine indices. * New Indices:: How to define your own indices.  File: texinfo, Node: Index Entries, Next: Predefined Indices, Up: Indices 13.1 Making Index Entries ========================= When you are making index entries, it is good practice to think of the different ways people may look for something. Different people _do not_ think of the same words when they look something up. A helpful index will have items indexed under all the different words that people may use. For example, one reader may think it obvious that the two-letter names for indices should be listed under "Indices, two-letter names", since the word "Index" is the general concept. But another reader may remember the specific concept of two-letter names and search for the entry listed as "Two letter names for indices". A good index will have both entries and will help both readers. Like typesetting, the construction of an index is a highly skilled, professional art, the subtleties of which are not appreciated until you need to do it yourself. *Note Printing Indices & Menus::, for information about printing an index at the end of a book or creating an index menu in an Info file.  File: texinfo, Node: Predefined Indices, Next: Indexing Commands, Prev: Index Entries, Up: Indices 13.2 Predefined Indices ======================= Texinfo provides six predefined indices. Here are their nominal meanings, abbreviations, and the corresponding index entry commands: `cp' (`@cindex') concept index, for general concepts. `fn' (`@findex') function index, for function and function-like names (such as entry points of libraries). `ky' (`@kindex') keystroke index, for keyboard commands. `pg' (`@pindex') program index, for names of programs. `tp' (`@tindex') data type index, for type names (such as structures defined in header files). `vr' (`@vindex') variable index, for variable names (such as global variables of libraries). Not every manual needs all of these, and most manuals use only two or three at most. The present manual, for example, has two indices: a concept index and an @-command index (that is actually the function index but is called a command index in the chapter heading). You are not required to use the predefined indices strictly for their canonical purposes. For example, suppose you wish to index some C preprocessor macros. You could put them in the function index along with actual functions, just by writing `@findex' commands for them; then, when you print the "Function Index" as an unnumbered chapter, you could give it the title `Function and Macro Index' and all will be consistent for the reader. On the other hand, it is best not to stray too far from the meaning of the predefined indices. Otherwise, in the event that your text is combined with other text from other manuals, the index entries will not match up. Instead, define your own new index (*note New Indices::). We recommend having a single index in the final document whenever possible, however many source indices you use, since then readers have only one place to look. Two or more source indices can be combined into one output index using the `@synindex' or `@syncodeindex' commands (*note Combining Indices::).  File: texinfo, Node: Indexing Commands, Next: Combining Indices, Prev: Predefined Indices, Up: Indices 13.3 Defining the Entries of an Index ===================================== The data to make an index come from many individual indexing commands scattered throughout the Texinfo source file. Each command says to add one entry to a particular index; after formatting, the index will give the current page number or node name as the reference. An index entry consists of an indexing command at the beginning of a line followed, on the rest of the line, by the entry. For example, this section begins with the following five entries for the concept index: @cindex Defining indexing entries @cindex Index entries, defining @cindex Entries for an index @cindex Specifying index entries @cindex Creating index entries Each predefined index has its own indexing command--`@cindex' for the concept index, `@findex' for the function index, and so on, as listed in the previous section. Concept index entries consist of text. The best way to write an index is to choose entries that are terse yet clear. If you can do this, the index often looks better if the entries are not capitalized, but written just as they would appear in the middle of a sentence. (Capitalize proper names and acronyms that always call for upper case letters.) This is the case convention we use in most GNU manuals' indices. If you don't see how to make an entry terse yet clear, make it longer and clear--not terse and confusing. If many of the entries are several words long, the index may look better if you use a different convention: to capitalize the first word of each entry. But do not capitalize a case-sensitive name such as a C or Lisp function name or a shell command; that would be a spelling error. Whichever case convention you use, please use it consistently! Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so use upper and lower case as required for them. By default, entries for a concept index are printed in a small roman font and entries for the other indices are printed in a small `@code' font. You may change the way part of an entry is printed with the usual Texinfo commands, such as `@file' for file names (*note Marking Text::), and `@r' for the normal roman font (*note Fonts::). Caution: Do not use a colon in an index entry. In Info, a colon separates the menu entry name from the node name, so a colon in the entry itself confuses Info. *Note Menu Parts::, for more information about the structure of a menu entry.  File: texinfo, Node: Combining Indices, Next: New Indices, Prev: Indexing Commands, Up: Indices 13.4 Combining Indices ====================== Sometimes you will want to combine two disparate indices such as functions and concepts, perhaps because you have few enough entries that a separate index would look silly. You could put functions into the concept index by writing `@cindex' commands for them instead of `@findex' commands, and produce a consistent manual by printing the concept index with the title `Function and Concept Index' and not printing the `Function Index' at all; but this is not a robust procedure. It works only if your document is never included as part of another document that is designed to have a separate function index; if your document were to be included with such a document, the functions from your document and those from the other would not end up together. Also, to make your function names appear in the right font in the concept index, you would need to enclose every one of them between the braces of `@code'. * Menu: * syncodeindex:: How to merge two indices, using `@code' font for the merged-from index. * synindex:: How to merge two indices, using the default font of the merged-to index.  File: texinfo, Node: syncodeindex, Next: synindex, Up: Combining Indices 13.4.1 `@syncodeindex' ---------------------- When you want to combine functions and concepts into one index, you should index the functions with `@findex' and index the concepts with `@cindex', and use the `@syncodeindex' command to redirect the function index entries into the concept index. The `@syncodeindex' command takes two arguments; they are the name of the index to redirect, and the name of the index to redirect it to. The template looks like this: @syncodeindex FROM TO For this purpose, the indices are given two-letter names: `cp' concept index `fn' function index `vr' variable index `ky' key index `pg' program index `tp' data type index Write an `@syncodeindex' command before or shortly after the end-of-header line at the beginning of a Texinfo file. For example, to merge a function index with a concept index, write the following: @syncodeindex fn cp This will cause all entries designated for the function index to merge in with the concept index instead. To merge both a variables index and a function index into a concept index, write the following: @syncodeindex vr cp @syncodeindex fn cp The `@syncodeindex' command puts all the entries from the `from' index (the redirected index) into the `@code' font, overriding whatever default font is used by the index to which the entries are now directed. This way, if you direct function names from a function index into a concept index, all the function names are printed in the `@code' font as you would expect.  File: texinfo, Node: synindex, Prev: syncodeindex, Up: Combining Indices 13.4.2 `@synindex' ------------------ The `@synindex' command is nearly the same as the `@syncodeindex' command, except that it does not put the `from' index entries into the `@code' font; rather it puts them in the roman font. Thus, you use `@synindex' when you merge a concept index into a function index. *Note Printing Indices & Menus::, for information about printing an index at the end of a book or creating an index menu in an Info file.  File: texinfo, Node: New Indices, Prev: Combining Indices, Up: Indices 13.5 Defining New Indices ========================= In addition to the predefined indices, you may use the `@defindex' and `@defcodeindex' commands to define new indices. These commands create new indexing @-commands with which you mark index entries. The `@defindex' command is used like this: @defindex NAME The name of an index should be a two letter word, such as `au'. For example: @defindex au This defines a new index, called the `au' index. At the same time, it creates a new indexing command, `@auindex', that you can use to make index entries. Use this new indexing command just as you would use a predefined indexing command. For example, here is a section heading followed by a concept index entry and two `au' index entries. @section Cognitive Semantics @cindex kinesthetic image schemas @auindex Johnson, Mark @auindex Lakoff, George (Evidently, `au' serves here as an abbreviation for "author".) In general, Texinfo constructs the new indexing command by concatenating the name of the index with `index'; thus, defining an `xy' index leads to the automatic creation of an `@xyindex' command. Use the `@printindex' command to print the index, as you do with the predefined indices. For example: @node Author Index @unnumbered Author Index @printindex au The `@defcodeindex' is like the `@defindex' command, except that, in the printed output, it prints entries in an `@code' font by default instead of a roman font. You should define new indices before the end-of-header line of a Texinfo file, and (of course) before any `@synindex' or `@syncodeindex' commands (*note Texinfo File Header::).  File: texinfo, Node: Insertions, Next: Breaks, Prev: Indices, Up: Top 14 Special Insertions ********************* Texinfo provides several commands for inserting characters that have special meaning in Texinfo, such as braces, and for other graphic elements that do not correspond to simple characters you can type. * Menu: * Atsign Braces Comma:: Inserting @ and {} and ,. * Inserting Quote Characters:: Inserting left and right quotes, in code. * Inserting Space:: How to insert the right amount of space within a sentence. * Inserting Accents:: How to insert accents and special characters. * Inserting Quotation Marks:: How to insert quotation marks. * Dots Bullets:: How to insert dots and bullets. * TeX and copyright:: How to insert the TeX logo and the copyright symbol. * euro:: How to insert the Euro currency symbol. * pounds:: How to insert the pounds currency symbol. * textdegree:: How to insert the degrees symbol. * minus:: How to insert a minus sign. * geq leq:: How to insert greater/less-than-or-equal signs. * math:: How to format a mathematical expression. * Click Sequences:: Inserting GUI usage sequences. * Glyphs:: How to indicate results of evaluation, expansion of macros, errors, etc.  File: texinfo, Node: Atsign Braces Comma, Next: Inserting Quote Characters, Up: Insertions 14.1 Inserting @ and {} and , ============================= `@' and curly braces are special characters in Texinfo. To insert these characters so they appear in text, you must put an `@' in front of these characters to prevent Texinfo from misinterpreting them. The comma `,' is a special character only in one uncommon context: it separates arguments to commands that take multiple arguments. * Menu: * Inserting an Atsign:: * Inserting Braces:: * Inserting a Comma::  File: texinfo, Node: Inserting an Atsign, Next: Inserting Braces, Up: Atsign Braces Comma 14.1.1 Inserting `@' with `@@' ------------------------------ `@@' stands for a single `@' in either printed or Info output. Do not put braces after an `@@' command.  File: texinfo, Node: Inserting Braces, Next: Inserting a Comma, Prev: Inserting an Atsign, Up: Atsign Braces Comma 14.1.2 Inserting `{' and `}' with `@{' and `@}' ----------------------------------------------- `@{' stands for a single `{' in either printed or Info output. `@}' stands for a single `}' in either printed or Info output. Do not put braces after either an `@{' or an `@}' command.  File: texinfo, Node: Inserting a Comma, Prev: Inserting Braces, Up: Atsign Braces Comma 14.1.3 Inserting `,' with `@comma{}' ------------------------------------ Ordinarily, a comma `,' is a normal character that can be simply typed in your input where you need it. However, Texinfo uses the comma as a special character in one uncommon context: some commands, such as `@acronym' (*note acronym::) and `@xref' (*note Cross References::), as well as user-defined macros (*note Defining Macros::), can take more than one argument. In these cases, the comma character is used to separate arguments. Since a comma character would confuse Texinfo's parsing for these commands, you must use the command `@comma{}' instead if you want to pass an actual comma. Here are some examples: @acronym{ABC, A Bizarre @comma{}} @xref{Comma,, The @comma{} symbol} @mymac{One argument@comma{} containing a comma} Although , can be used nearly anywhere, there is no need for it anywhere except in this unusual case.  File: texinfo, Node: Inserting Quote Characters, Next: Inserting Space, Prev: Atsign Braces Comma, Up: Insertions 14.2 Inserting Quote Characters =============================== As explained in the early section on general Texinfo input conventions (*note Conventions::), Texinfo source files use the ASCII character ``' (96 decimal) to produce a left quote (`), and ASCII `'' (39 decimal) to produce a right quote ('). Doubling these input characters (```' and `''') produces double quotes (" and "). These are the conventions used by TeX. This works all right for text. However, in examples of computer code, readers are especially likely to cut and paste the text verbatim--and, unfortunately, some document viewers will mangle these characters. (The free PDF reader `xpdf' works fine, but other PDF readers, both free and nonfree, have problems.) If this is a concern for your document, Texinfo provides two special settings via `@set': `@set txicodequoteundirected' causes the output for the `'' character to be the undirected single quote, like this: `''. `@set txicodequotebacktick' Cause the output for the ``' character to be the standalone grave accent, like this: ``'. `xyza`'bc' If you want these settings for only part of the document, `@clear' will restore the normal behavior, as in `@clear txicodequoteundirected'. These settings affect `@code', `@example', and `@verbatim'; they do not affect `@samp'. (*Note Useful Highlighting::.)  File: texinfo, Node: Inserting Space, Next: Inserting Accents, Prev: Inserting Quote Characters, Up: Insertions 14.3 Inserting Space ==================== The following sections describe commands that control spacing of various kinds within and after sentences. * Menu: * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. * Ending a Sentence:: Sometimes it does. * Multiple Spaces:: Inserting multiple spaces. * frenchspacing:: Specifying end-of-sentence spacing. * dmn:: How to format a dimension.  File: texinfo, Node: Not Ending a Sentence, Next: Ending a Sentence, Up: Inserting Space 14.3.1 Not Ending a Sentence ---------------------------- Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, less or more space is inserted after a period in a typeset manual. Since it is not always possible to determine when a period ends a sentence and when it is used in an abbreviation, special commands are needed in some circumstances. Usually, Texinfo can guess how to handle periods, so you do not need to use the special commands; you just enter a period as you would if you were using a typewriter, which means you put two spaces after the period, question mark, or exclamation mark that ends a sentence. Use the `@:' command after a period, question mark, exclamation mark, or colon that should not be followed by extra space. For example, use `@:' after periods that end abbreviations which are not at the ends of sentences. For example, foo vs.@: bar foo vs. bar produces foo vs. bar foo vs. bar `@:' has no effect on the Info and HTML output. In Docbook and XML, the previous punctuation character (.?!:) is output as an entity instead of as the normal character: `. ? ! :'. This gives further processors a chance to notice and not add the usual extra space. Do not put braces after `@:' (or any non-alphabetic command).  File: texinfo, Node: Ending a Sentence, Next: Multiple Spaces, Prev: Not Ending a Sentence, Up: Inserting Space 14.3.2 Ending a Sentence ------------------------ Use `@.' instead of a period, `@!' instead of an exclamation point, and `@?' instead of a question mark at the end of a sentence that ends with a capital letter. Otherwise, TeX will think the letter is an abbreviation and will not insert the correct end-of-sentence spacing. Here is an example: Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@. Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. produces Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. Give it to M.I.B. and to M.E.W. Also, give it to R.J.C. In the Info file output, `@.' is equivalent to a simple `.'; likewise for `@!' and `@?'. The meanings of `@:' and `@.' in Texinfo are designed to work well with the Emacs sentence motion commands (*note Sentences: (emacs)Sentences.). Do not put braces after any of these commands.  File: texinfo, Node: Multiple Spaces, Next: frenchspacing, Prev: Ending a Sentence, Up: Inserting Space 14.3.3 Multiple Spaces ---------------------- Ordinarily, TeX collapses multiple whitespace characters (space, tab, and newline) into a single space. Info output, on the other hand, preserves whitespace as you type it, except for changing a newline into a space; this is why it is important to put two spaces at the end of sentences in Texinfo documents. Occasionally, you may want to actually insert several consecutive spaces, either for purposes of example (what your program does with multiple spaces as input), or merely for purposes of appearance in headings or lists. Texinfo supports three commands: `@SPACE', `@TAB', and `@NL', all of which insert a single space into the output. (Here, `@SPACE' represents an `@' character followed by a space, i.e., `@ ', and `TAB' and `NL' represent the tab character and end-of-line, i.e., when `@' is the last character on a line.) For example, Spacey@ @ @ @ example. produces Spacey example. Other possible uses of `@SPACE' have been subsumed by `@multitable' (*note Multi-column Tables::). Do not follow any of these commands with braces. To produce a non-breakable space, see *note `@tie': tie.  File: texinfo, Node: frenchspacing, Next: dmn, Prev: Multiple Spaces, Up: Inserting Space 14.3.4 `@frenchspacing' VAL: Control sentence spacing ----------------------------------------------------- In American typography, it is traditional and correct to put extra space at the end of a sentence, after a semi-colon, and so on. This is the default in Texinfo. In French typography (and many others), this extra space is wrong; all spaces are uniform. Therefore Texinfo provides the `@frenchspacing' command to control the spacing after punctuation. It reads the rest of the line as its argument, which must be the single word `on' or `off' (always these words, regardless of the language) of the document. Here is an example: @frenchspacing on This is text. Two sentences. Three sentences. French spacing. @frenchspacing off This is text. Two sentences. Three sentences. Non-French spacing. produces (there will be no difference in Info): This is text. Two sentences. Three sentences. French spacing. This is text. Two sentences. Three sentences. Non-French spacing. `@frenchspacing' mainly affects the printed output, including the output after `@.', `@!', and `@?' (*note Ending a Sentence::). In Info, usually space characters in the input are written unaltered to the output, and `@frenchspacing' does not change this. It does change the one case where `makeinfo' outputs a space on its own: when a sentence ends at a newline in the source. Here's an example: Some sentence. Next sentence. produces in Info output, with `@frenchspacing off' (the default), two spaces between the sentences: Some sentence. Next sentence. With `@frenchspacing on', `makeinfo' outputs only a single space: Some sentence. Next sentence. `@frenchspacing' has no effect on the HTML or Docbook output; for XML, it outputs a transliteration of itself (*note Output Formats::).  File: texinfo, Node: dmn, Prev: frenchspacing, Up: Inserting Space 14.3.5 `@dmn'{DIMENSION}: Format a Dimension -------------------------------------------- At times, you may want to write `12pt' or `8.5in' with little or no space between the number and the abbreviation for the dimension. You can use the `@dmn' command to do this. On seeing the command, TeX inserts just enough space for proper typesetting; the Info formatting commands insert no space at all, since the Info file does not require it. To use the `@dmn' command, write the number and then follow it immediately, with no intervening space, by `@dmn', and then by the dimension within braces. For example, A4 paper is 8.27@dmn{in} wide. produces A4 paper is 8.27in wide. Not everyone uses this style. Some people prefer `8.27 in.@:' or `8.27 inches' to `8.27@dmn{in}' in the Texinfo file. In these cases, however, the formatters may insert a line break between the number and the dimension, so use `@w' (*note w::). Also, if you write a period after an abbreviation within a sentence, you should write `@:' after the period to prevent TeX from inserting extra whitespace, as shown here. *Note Not Ending a Sentence::.  File: texinfo, Node: Inserting Accents, Next: Inserting Quotation Marks, Prev: Inserting Space, Up: Insertions 14.4 Inserting Accents ====================== Here is a table with the commands Texinfo provides for inserting floating accents. They all need an argument, the character to accent, which can either be given in braces as usual (`@'{e}'), or, as a special case, the braces can be omitted, in which case the argument is the next character (`@'e'). This is to make the source as convenient as possible to type and read, since accented characters are very common in some languages. If the command is alphabetic, such as `@dotaccent', then there must be a space between the command name and argument if braces are not used. If the command is non-alphabetic, such as `@'', then there must _not_ be a space; the argument is the very next character. Exception: the argument to `@tieaccent' must be enclosed in braces (since it is two characters instead of one). To get the true accented characters output in Info, not just the ASCII transliterations, it is necessary to specify `@documentencoding' with an encoding which supports the required characters (*note `@documentencoding': documentencoding.). In this case, you can also use non-ASCII (e.g., pre-accented) characters in the source file. Command Output What ------------------------------------------------------ @"o o" umlaut accent @'o o' acute accent @,{c} c, cedilla accent @=o o= macron/overbar accent @^o o^ circumflex accent @`o o` grave accent @~o o~ tilde accent @dotaccent{o} o. overdot accent @H{o} o'' long Hungarian umlaut @ringaccent{o} o* ring accent @tieaccent{oo} oo[ tie-after accent @u{o} o( breve accent @ubaraccent{o} o_ underbar accent @udotaccent{o} .o underdot accent @v{o} o< hacek/check/caron accent This table lists the Texinfo commands for inserting other characters commonly used in languages other than English. @exclamdown{} ! upside-down ! @questiondown{} ? upside-down ? @aa{} @AA{} aa AA a,A with circle @ae{} @AE{} ae AE ae,AE ligatures @dotless{i} i dotless i @dotless{j} j dotless j @l{} @L{} /l /L suppressed-L,l @o{} @O{} /o /O O,o with slash @oe{} @OE{} oe OE oe,OE ligatures @ordf{} @ordm{} a o Spanish ordinals @ss{} ss es-zet or sharp S  File: texinfo, Node: Inserting Quotation Marks, Next: Dots Bullets, Prev: Inserting Accents, Up: Insertions 14.5 Inserting Quotation Marks ============================== Use doubled single-quote characters to begin and end quotations: ``...''. TeX converts two single quotes to left- and right-hand doubled quotation marks, and Info converts doubled single-quote characters to ASCII double-quotes: ``...'' becomes "...". You may occasionally need to produce two consecutive single quotes; for example, in documenting a computer language such as Maxima where '' is a valid command. You can do this with the input '@w{}'; the empty `@w' command stops the combination into the double-quote characters. The left quote character (`, ASCII code 96) used in Texinfo is a grave accent in ANSI and ISO character set standards. We use it as a quote character because that is how TeX is set up, by default. Texinfo supports several other quotation marks used in languages other than English. Below is a table with the commands Texinfo provides for inserting quotation marks. In order to get the symbols for the quotation marks in encoded Info output, it is necessary to specify `@documentencoding UTF-8'. (*Note `@documentencoding': documentencoding.) Double guillemets are also present in ISO 8859-1 (aka Latin 1) and ISO 8859-15 (aka Latin 9). The standard TeX fonts support the usual quotation marks used in English (the ones produced with single and doubled ASCII single-quotes). For the other quotation marks, TeX uses European Computer Modern (EC) fonts (`ecrm1000' and other variants). These fonts are freely available, of course; you can download them from `http://www.ctan.org/tex-archive/fonts/ec', among other places. The free EC fonts are bitmap fonts created with Metafont. Especially for on-line viewing, Type 1 (vector) versions of the fonts are preferable; these are available in the CM-Super font package (`http://www.ctan.org/tex-archive/fonts/ps-type1/cm-super'). Both distributions include installation instructions. Command Glyph Unicode name (point) ------------------------------------------------------------------------------------ @quotedblleft{} `` " Left double quotation mark (U+201C) @quotedblright{} '' " Right double quotation mark (U+201D) @quoteleft{} ` ` Left single quotation mark (U+2018) @quoteright{} ' ' Right single quotation mark (U+2019) @quotedblbase{} " Double low-9 quotation mark (U+201E) @quotesinglbase{} , Single low-9 quotation mark (U+201A) @guillemetleft{} << Left-pointing double angle quotation mark (U+00AB) @guillemetright{} >> Right-pointing double angle quotation mark (U+00BB) @guilsinglleft{} < Single left-pointing angle quotation mark (U+2039) @guilsinglright{} > Single right-pointing angle quotation mark (U+203A) For the double angle quotation marks, Adobe and LaTeX glyph names are also supported: `@guillemotleft' and `@guillemotright'. These names are actually incorrect; a "guillemot" is a bird species (a type of auk). Traditions for quotation mark usage vary to a great extent between languages (`http://en.wikipedia.org/wiki/Quotation_mark%2C_non-English_usage#Overview'). Texinfo does not provide commands for typesetting quotation marks according to the numerous traditions. Therefore, you have to choose the commands appropriate for the language of your manual. Sometimes aliases (*note `@alias': alias.) can simplify the usage and make the source code more readable. For example, in German, `@quotedblbase' is used for the left double quote, and the right double quote is actually `@quotedblleft', which is counter-intuitive. Thus, in this case the following aliases would be convenient: @alias lgqq = quotedblbase @alias rgqq = quotedblleft  File: texinfo, Node: Dots Bullets, Next: TeX and copyright, Prev: Inserting Quotation Marks, Up: Insertions 14.6 Inserting Ellipsis and Bullets =================================== An "ellipsis" (a line of dots) is not typeset as a string of periods, so a special command is used for ellipsis in Texinfo. The `@bullet' command is special, too. Each of these commands is followed by a pair of braces, `{}', without any whitespace between the name of the command and the braces. (You need to use braces with these commands because you can use them next to other text; without the braces, the formatters would be confused. *Note @-Command Syntax: Command Syntax, for further information.) * Menu: * dots:: How to insert dots ... * bullet:: How to insert a bullet.  File: texinfo, Node: dots, Next: bullet, Up: Dots Bullets 14.6.1 `@dots'{} (...) and `@enddots'{} (...) --------------------------------------------- Use the `@dots{}' command to generate an ellipsis, which is three dots in a row, appropriately spaced ... like so. Do not simply write three periods in the input file; that would work for the Info file output, but would produce the wrong amount of space between the periods in the printed manual. Similarly, the `@enddots{}' command generates an end-of-sentence ellipsis, which has different spacing afterwards, ... Look closely to see the difference.  File: texinfo, Node: bullet, Prev: dots, Up: Dots Bullets 14.6.2 `@bullet'{} (*) ---------------------- Use the `@bullet{}' command to generate a large round dot, or the closest possible thing to one. In Info, an asterisk is used. Here is a bullet: * When you use `@bullet' in `@itemize', you do not need to type the braces, because `@itemize' supplies them. (*Note `@itemize': itemize.)  File: texinfo, Node: TeX and copyright, Next: euro, Prev: Dots Bullets, Up: Insertions 14.7 Inserting TeX and Legal Symbols: (C), (R) ============================================== The logo `TeX' is typeset in a special fashion and it needs an @-command. The copyright and registered symbols, `(C)' and `(R)', is also special. Each of these commands is followed by a pair of braces, `{}', without any whitespace between the name of the command and the braces. * Menu: * tex:: The TeX logos. * copyright symbol:: The copyright symbol (c in a circle). * registered symbol:: The registered symbol (R in a circle).  File: texinfo, Node: tex, Next: copyright symbol, Up: TeX and copyright 14.7.1 `@TeX'{} (TeX) and `@LaTeX'{} (LaTeX) -------------------------------------------- Use the `@TeX{}' command to generate `TeX'. In a printed manual, this is a special logo that is different from three ordinary letters. In Info, it just looks like `TeX'. Similarly, use the `@LaTeX{}' command to generate `LaTeX', which is even more special in printed manuals (and different from the incorrect `La@TeX{}'. In Info, the result is just `LaTeX'. (LaTeX is another macro package built on top of TeX, very loosely analogous to Texinfo in that it emphasizes logical structure, but much (much) larger.) The spelling of these commands are unusual among Texinfo commands in that they use both uppercase and lowercase letters.  File: texinfo, Node: copyright symbol, Next: registered symbol, Prev: tex, Up: TeX and copyright 14.7.2 `@copyright{}' ((C)) --------------------------- Use the `@copyright{}' command to generate the copyright symbol, `(C)'. Where possible, this is a `c' inside a circle; in Info, this is `(C)'.  File: texinfo, Node: registered symbol, Prev: copyright symbol, Up: TeX and copyright 14.7.3 `@registeredsymbol{}' ((R)) ---------------------------------- Use the `@registeredsymbol{}' command to generate the registered symbol, `(R)'. Where possible, this is an `R' inside a circle; in Info, this is `(R)'.  File: texinfo, Node: euro, Next: pounds, Prev: TeX and copyright, Up: Insertions 14.8 `@euro'{} (Euro ): Euro Currency Symbol ============================================ Use the `@euro{}' command to generate `Euro '. Where possible, this is the symbol for the Euro currency, invented as part of the European economic unification. In plain Info, it is the word `Euro '. A trailing space is included in the text transliteration since typically no space is desired after the symbol, so it would be inappropriate to have a space in the source document. Texinfo cannot magically synthesize support for the Euro symbol where the underlying system (fonts, software, whatever) does not support it. Therefore, in many cases it is preferable to use the word "Euro". (In banking circles, the abbreviation for the Euro is EUR.) In order to get the Euro symbol in encoded Info output, for example, it is necessary to specify `@documentencoding ISO-8859-15'. (*Note `@documentencoding': documentencoding.) The Euro symbol is in ISO 8859-15 (aka Latin 9), and is _not_ in the more widely-used and supported ISO 8859-1 (Latin 1). The Euro symbol does not exist in the standard TeX fonts (which were designed before the Euro was legislated into existence). Therefore, TeX uses an additional font, named `feymr10' (along with other variables). It is freely available, of course; you can download it from `http://www.ctan.org/tex-archive/fonts/eurosym', among other places. The distribution includes installation instructions.  File: texinfo, Node: pounds, Next: textdegree, Prev: euro, Up: Insertions 14.9 `@pounds'{} (#): Pounds Sterling ===================================== Use the `@pounds{}' command to generate `#'. Where possible, this is the symbol for the currency pounds sterling. In Info, it is a `#'.  File: texinfo, Node: textdegree, Next: minus, Prev: pounds, Up: Insertions 14.10 `@textdegree'{} (o): Degrees Symbol ========================================= Use the `@textdegree{}' command to generate `o'. Where possible, this is the normal symbol for degrees. In plain text and Info output, it is an `o'.  File: texinfo, Node: minus, Next: geq leq, Prev: textdegree, Up: Insertions 14.11 `@minus'{} (-): Inserting a Minus Sign ============================================ Use the `@minus{}' command to generate a minus sign. In a fixed-width font, this is a single hyphen, but in a proportional font, the symbol is the customary length for a minus sign--a little longer than a hyphen, shorter than an em-dash: `-' is a minus sign generated with `@minus{}', `-' is a hyphen generated with the character `-', `--' is an em-dash for text. In the fixed-width font used by Info, `@minus{}' is the same as a hyphen. You should not use `@minus{}' inside `@code' or `@example' because the width distinction is not made in the fixed-width font they use. When you use `@minus' to specify the mark beginning each entry in an itemized list, you do not need to type the braces (*note `@itemize': itemize.).  File: texinfo, Node: geq leq, Next: math, Prev: minus, Up: Insertions 14.12 `@geq{}' (>=) and `@leq{}' (<=): Inserting relations ========================================================== Use the `@geq{}' and `@geq{}' commands to generate greater-than-or-equal and less-than-equal-signs, `>=' and `<='. In plain text and Info output, these are the ASCII sequences `>=' and `<='. The  File: texinfo, Node: math, Next: Click Sequences, Prev: geq leq, Up: Insertions 14.13 `@math': Inserting Mathematical Expressions ================================================= You can write a short mathematical expression with the `@math' command. Write the mathematical expression between braces, like this: @math{(a + b)(a + b) = a^2 + 2ab + b^2} This produces the following in Info and HTML: (a + b)(a + b) = a^2 + 2ab + b^2 The `@math' command has no special effect on the Info and HTML output. `makeinfo' expands any `@'-commands as usual, but it does not try to produce good mathematical formatting in any way. However, as far as the TeX output is concerned, plain TeX mathematical commands are allowed in `@math', starting with `\', and the plain TeX math characters like `^' and `_' are also recognized. In essence, `@math' drops you into plain TeX math mode. This allows you to conveniently write superscripts and subscripts (as in the above example), and also to use all the plain TeX math control sequences for symbols, functions, and so on, and thus get proper formatting in the TeX output, at least. It's best to use `\' instead of `@' for any such mathematical commands; otherwise, `makeinfo' will complain. On the other hand, input with matching (but unescaped) braces, such as `k_{75}', is allowed inside `@math', although `makeinfo' would complain about the bare braces in regular input. Here's an example: @math{\sin 2\pi \equiv \cos 3\pi} which looks like the input in Info and HTML: \sin 2\pi \equiv \cos 3\pi Since `\' is an escape character inside `@math', you can use `@\' to get a literal backslash (`\\' will work in TeX, but you'd get the literal `\\' in Info). `@\' is not defined outside of `@math', since a `\' ordinarily produces a literal `\'. For displayed equations, you must at present use TeX directly (*note Raw Formatter Commands::).  File: texinfo, Node: Click Sequences, Next: Glyphs, Prev: math, Up: Insertions 14.14 Click Sequences ===================== When documenting graphical interfaces, it is necessary to describe sequences such as `Click on `File', then choose `Open', then ...'. Texinfo offers commands `@clicksequence' and `click' to represent this, typically used like this: ... @clicksequence{File @click{} Open} ... which produces: ... File -> Open ... The `@click' command produces a simple right arrow (`->' in Info) by default; this glyph is also available independently via the command `@arrow{}'. You can change the glyph produced by `@click' with the command `@clickstyle', which takes a command name as its single argument on the rest of the line, much like `@itemize' and friends (*note `@itemize': itemize.). The command should produce a glyph, and the usual empty braces `{}' are omitted. Here's an example: @clickstyle @result ... @clicksequence{File @click{} Open} ... now produces: ... File => Open ...  File: texinfo, Node: Glyphs, Prev: Click Sequences, Up: Insertions 14.15 Glyphs for Examples ========================= In Texinfo, code is often illustrated in examples that are delimited by `@example' and `@end example', or by `@lisp' and `@end lisp'. In such examples, you can indicate the results of evaluation or an expansion using `=>' or `==>'. Likewise, there are commands to insert glyphs to indicate printed output, error messages, equivalence of expressions, and the location of point. The glyph-insertion commands do not need to be used within an example, but most often they are. Every glyph-insertion command is followed by a pair of left- and right-hand braces. * Menu: * Glyphs Summary:: * result:: How to show the result of expression. * expansion:: How to indicate an expansion. * Print Glyph:: How to indicate printed output. * Error Glyph:: How to indicate an error message. * Equivalence:: How to indicate equivalence. * Point Glyph:: How to indicate the location of point.  File: texinfo, Node: Glyphs Summary, Next: result, Up: Glyphs 14.15.1 Glyphs Summary ---------------------- Here are the different glyph commands: => `@result{}' points to the result of an expression. ==> `@expansion{}' shows the results of a macro expansion. -| `@print{}' indicates printed output. error--> `@error{}' indicates that the following text is an error message. == `@equiv{}' indicates the exact equivalence of two forms. -!- `@point{}' shows the location of point. * Menu: * result:: * expansion:: * Print Glyph:: * Error Glyph:: * Equivalence:: * Point Glyph::  File: texinfo, Node: result, Next: expansion, Prev: Glyphs Summary, Up: Glyphs 14.15.2 `@result{}' (=>): Indicating Evaluation ----------------------------------------------- Use the `@result{}' command to indicate the result of evaluating an expression. The `@result{}' command is displayed as `=>' in Info and HTML and as a true double stemmed arrow in the printed output. Thus, the following, (cdr '(1 2 3)) => (2 3) may be read as "`(cdr '(1 2 3))' evaluates to `(2 3)'".  File: texinfo, Node: expansion, Next: Print Glyph, Prev: result, Up: Glyphs 14.15.3 `@expansion{}' (==>): Indicating an Expansion ----------------------------------------------------- When an expression is a macro call, it expands into a new expression. You can indicate the result of the expansion with the `@expansion{}' command. The `@expansion{}' command is displayed as `==>' in Info and HTML, and as a long arrow with a flat base in the printed output. For example, the following @lisp (third '(a b c)) @expansion{} (car (cdr (cdr '(a b c)))) @result{} c @end lisp produces (third '(a b c)) ==> (car (cdr (cdr '(a b c)))) => c which may be read as: `(third '(a b c))' expands to `(car (cdr (cdr '(a b c))))'; the result of evaluating the expression is `c'. Often, as in this case, an example looks better if the `@expansion{}' and `@result{}' commands are indented.  File: texinfo, Node: Print Glyph, Next: Error Glyph, Prev: expansion, Up: Glyphs 14.15.4 `@print{}' (-|): Indicating Printed Output -------------------------------------------------- Sometimes an expression will print output during its execution. You can indicate the printed output with the `@print{}' command. The `@print{}' command is displayed as `-|' in Info and HTML and (similarly) as a horizontal dash butting against a vertical bar in the printed output. In the following example, the printed text is indicated with `-|', and the value of the expression follows on the last line. (progn (print 'foo) (print 'bar)) -| foo -| bar => bar In a Texinfo source file, this example is written as follows: @lisp (progn (print 'foo) (print 'bar)) @print{} foo @print{} bar @result{} bar @end lisp  File: texinfo, Node: Error Glyph, Next: Equivalence, Prev: Print Glyph, Up: Glyphs 14.15.5 `@error{}' (error-->): Indicating an Error Message ---------------------------------------------------------- A piece of code may cause an error when you evaluate it. You can designate the error message with the `@error{}' command. The `@error{}' command is displayed as `error-->' in Info and HTML and as the word `error' in a box in the printed output. Thus, @lisp (+ 23 'x) @error{} Wrong type argument: integer-or-marker-p, x @end lisp produces (+ 23 'x) error--> Wrong type argument: integer-or-marker-p, x This indicates that the following error message is printed when you evaluate the expression: Wrong type argument: integer-or-marker-p, x `error-->' itself is not part of the error message.  File: texinfo, Node: Equivalence, Next: Point Glyph, Prev: Error Glyph, Up: Glyphs 14.15.6 `@equiv{}' (==): Indicating Equivalence ----------------------------------------------- Sometimes two expressions produce identical results. You can indicate the exact equivalence of two forms with the `@equiv{}' command. The `@equiv{}' command is displayed as `==' in Info and HTML and as a standard mathematical equivalence sign (three parallel horizontal lines) in the printed output. Thus, @lisp (make-sparse-keymap) @equiv{} (list 'keymap) @end lisp produces (make-sparse-keymap) == (list 'keymap) This indicates that evaluating `(make-sparse-keymap)' produces identical results to evaluating `(list 'keymap)'.  File: texinfo, Node: Point Glyph, Prev: Equivalence, Up: Glyphs 14.15.7 `@point{}' (-!-): Indicating Point in a Buffer ------------------------------------------------------ Sometimes you need to show an example of text in an Emacs buffer. In such examples, the convention is to include the entire contents of the buffer in question between two lines of dashes containing the buffer name. You can use the `@point{}' command to show the location of point in the text in the buffer. (The symbol for point, of course, is not part of the text in the buffer; it indicates the place _between_ two characters where point is located.) The `@point{}' command is displayed as `-!-' in Info and HTML and as a small five pointed star in the printed output. The following example shows the contents of buffer `foo' before and after evaluating a Lisp command to insert the word `changed'. ---------- Buffer: foo ---------- This is the -!-contents of foo. ---------- Buffer: foo ---------- (insert "changed ") => nil ---------- Buffer: foo ---------- This is the changed -!-contents of foo. ---------- Buffer: foo ---------- In a Texinfo source file, the example is written like this: @example ---------- Buffer: foo ---------- This is the @point{}contents of foo. ---------- Buffer: foo ---------- (insert "changed ") @result{} nil ---------- Buffer: foo ---------- This is the changed @point{}contents of foo. ---------- Buffer: foo ---------- @end example  File: texinfo, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top 15 Forcing and Preventing Breaks ******************************** Usually, a Texinfo file is processed both by TeX and by one of the Info formatting commands. Line, paragraph, or page breaks sometimes occur in the `wrong' place in one or other form of output. You must ensure that text looks right both in the printed manual and in the Info file. For example, in a printed manual, page breaks may occur awkwardly in the middle of an example; to prevent this, you can hold text together using a grouping command that keeps the text from being split across two pages. Conversely, you may want to force a page break where none would occur normally. Fortunately, problems like these do not often arise. When they do, use the break, break prevention, or pagination commands. * Menu: * Break Commands:: Summary of break-related commands. * Line Breaks:: Forcing line breaks. * - and hyphenation:: Helping TeX with hyphenation points. * allowcodebreaks:: Controlling line breaks within @code text. * w:: Preventing unwanted line breaks in text. * tie:: Inserting an unbreakable but varying space. * sp:: Inserting blank lines. * page:: Forcing the start of a new page. * group:: Preventing unwanted page breaks. * need:: Another way to prevent unwanted page breaks.  File: texinfo, Node: Break Commands, Next: Line Breaks, Up: Breaks 15.1 Break Commands =================== The break commands create or allow line and paragraph breaks: `@*' Force a line break. `@sp N' Skip N blank lines. `@-' Insert a discretionary hyphen. `@hyphenation{HY-PHEN-A-TED WORDS}' Define hyphen points in HY-PHEN-A-TED WORDS. These commands hold text together on a single line: `@w{TEXT}' Prevent TEXT from being split and hyphenated across two lines. `@tie{}' Insert a normal interword space at which a line break may not occur. The pagination commands apply only to printed output, since Info files do not have pages. `@page' Start a new page in the printed manual. `@group' Hold text together that must appear on one printed page. `@need MILS' Start a new printed page if not enough space on this one.  File: texinfo, Node: Line Breaks, Next: - and hyphenation, Prev: Break Commands, Up: Breaks 15.2 `@*' and `@/': Generate and Allow Line Breaks ================================================== The `@*' command forces a line break in both the printed manual and in Info. The `@/' command allows a line break (printed manual only). Here is an example with `@*': This line @* is broken @*in two places. produces This line is broken in two places. The `@/' command can be useful within a url (*note `@uref': uref.), which tend to be long and are otherwise unbreakable. For example: The official Texinfo home page is on the GNU web site: @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}. produces The official Texinfo home page is on the GNU web site: `http://www.gnu.org/software/gnu/texinfo'. Without the `@/' commands, TeX would have nowhere to break the line. `@/' has no effect in the online output.  File: texinfo, Node: - and hyphenation, Next: allowcodebreaks, Prev: Line Breaks, Up: Breaks 15.3 `@-' and `@hyphenation': Helping TeX Hyphenate =================================================== Although TeX's hyphenation algorithm is generally pretty good, it does miss useful hyphenation points from time to time. (Or, far more rarely, insert an incorrect hyphenation.) So, for documents with an unusual vocabulary or when fine-tuning for a printed edition, you may wish to help TeX out. Texinfo supports two commands for this: `@-' Insert a discretionary hyphen, i.e., a place where TeX can (but does not have to) hyphenate. This is especially useful when you notice an overfull hbox is due to TeX missing a hyphenation (*note Overfull hboxes::). TeX will not insert any hyphenation points itself into a word containing `@-'. `@hyphenation{HY-PHEN-A-TED WORDS}' Tell TeX how to hyphenate HY-PHEN-A-TED WORDS. As shown, you put a `-' at each hyphenation point. For example: @hyphenation{man-u-script man-u-scripts} TeX only uses the specified hyphenation points when the words match exactly, so give all necessary variants, such as plurals. Info, HTML, and other non-TeX output is not hyphenated, so none of these commands have any effect there.  File: texinfo, Node: allowcodebreaks, Next: w, Prev: - and hyphenation, Up: Breaks 15.4 `@allowcodebreaks': Control Line Breaks in `@code' ======================================================= Ordinarily, TeX will consider breaking lines at `-' and `_' characters within `@code' and related commands (*note `@code': code.), more or less as if they were "empty" hyphenation points. This is necessary as many manuals, especially for Lisp-family languages, must document very long identifiers. On the other hand, other manuals don't have this problems, and you may not wish to allow a line break at the underscore in, for example, `SIZE_MAX', or even worse, after any of the four underscores in `__typeof__'. So Texinfo provides this command: @allowcodebreaks false to prevent TeX from breaking at `-' or `_' within `@code'. You can go back to allowing such breaks with `@allowcodebreaks true'. Write these commands on lines by themselves. These commands can be given anywhere in the document. For example, you may have just one problematic paragraph where you need to turn off the breaks, but want them in general, or vice versa. This command has no effect in Info, HTML, and other non-TeX output.  File: texinfo, Node: w, Next: tie, Prev: allowcodebreaks, Up: Breaks 15.5 `@w'{TEXT}: Prevent Line Breaks ==================================== `@w{TEXT}' outputs TEXT and prohibits line breaks within TEXT, for both TeX and `makeinfo'. Thus, you can use `@w' to produce a non-breakable space, fixed at the width of a normal interword space: @w{ } @w{ } @w{ } indentation. produces: indentation. The space from `@w{ }', as well as being non-breakable, also will not stretch or shrink. Sometimes that is what you want, for instance if you're doing manual indenting. However, usually you want a normal interword space that does stretch and shrink (in the printed output); see the `@tie' command in the next section. You can also use the `@w' command to prevent TeX from automatically hyphenating a long name or phrase that happens to fall near the end of a line. `makeinfo' does not ever hyphenate words. You can also use `@w' to avoid unwanted keyword expansion in source control systems. For example, to literally write $Id$ in your document, use `@w{$}Id$'.  File: texinfo, Node: tie, Next: sp, Prev: w, Up: Breaks 15.6 `@tie{}': Inserting an Unbreakable Space ============================================= The `@tie{}' command produces a normal interword space at which a line break may not occur. Always write it with following (empty) braces, as usual for commands used within a paragraph. Here's an example: @TeX{} was written by Donald E.@tie{}Knuth. produces: TeX was written by Donald E. Knuth. There are two important differences between `@tie{}' and `@w{ }': * The space produced by `@tie{}' will stretch and shrink slightly along with the normal interword spaces in the paragraph; the space produced by `@w{ }' will not vary. * `@tie{}' allows hyphenation of the surrounding words, while `@w{ }' inhibits hyphenation of those words (for TeXnical reasons, namely that it produces an `\hbox').  File: texinfo, Node: sp, Next: page, Prev: tie, Up: Breaks 15.7 `@sp' N: Insert Blank Lines ================================ A line beginning with and containing only `@sp N' generates N blank lines of space in both the printed manual and the Info file. `@sp' also forces a paragraph break. For example, @sp 2 generates two blank lines. The `@sp' command is most often used in the title page.  File: texinfo, Node: page, Next: group, Prev: sp, Up: Breaks 15.8 `@page': Start a New Page ============================== A line containing only `@page' starts a new page in a printed manual. The command has no effect on Info files since they are not paginated. An `@page' command is often used in the `@titlepage' section of a Texinfo file to start the copyright page.  File: texinfo, Node: group, Next: need, Prev: page, Up: Breaks 15.9 `@group': Prevent Page Breaks ================================== The `@group' command (on a line by itself) is used inside an `@example' or similar construct to begin an unsplittable vertical group, which will appear entirely on one page in the printed output. The group is terminated by a line containing only `@end group'. These two lines produce no output of their own, and in the Info file output they have no effect at all. Although `@group' would make sense conceptually in a wide variety of contexts, its current implementation works reliably only within `@example' and variants, and within `@display', `@format', `@flushleft' and `@flushright'. *Note Quotations and Examples::. (What all these commands have in common is that each line of input produces a line of output.) In other contexts, `@group' can cause anomalous vertical spacing. This formatting requirement means that you should write: @example @group ... @end group @end example with the `@group' and `@end group' commands inside the `@example' and `@end example' commands. The `@group' command is most often used to hold an example together on one page. In this Texinfo manual, more than 100 examples contain text that is enclosed between `@group' and `@end group'. If you forget to end a group, you may get strange and unfathomable error messages when you run TeX. This is because TeX keeps trying to put the rest of the Texinfo file onto the one page and does not start to generate error messages until it has processed considerable text. It is a good rule of thumb to look for a missing `@end group' if you get incomprehensible error messages in TeX.  File: texinfo, Node: need, Prev: group, Up: Breaks 15.10 `@need MILS': Prevent Page Breaks ======================================= A line containing only `@need N' starts a new page in a printed manual if fewer than N mils (thousandths of an inch) remain on the current page. Do not use braces around the argument N. The `@need' command has no effect on Info files since they are not paginated. This paragraph is preceded by an `@need' command that tells TeX to start a new page if fewer than 800 mils (eight-tenths inch) remain on the page. It looks like this: @need 800 This paragraph is preceded by ... The `@need' command is useful for preventing orphans (single lines at the bottoms of printed pages).  File: texinfo, Node: Definition Commands, Next: Conditionals, Prev: Breaks, Up: Top 16 Definition Commands ********************** The `@deffn' command and the other "definition commands" enable you to describe functions, variables, macros, commands, user options, special forms and other such artifacts in a uniform format. In the Info file, a definition causes the entity category--`Function', `Variable', or whatever--to appear at the beginning of the first line of the definition, followed by the entity's name and arguments. In the printed manual, the command causes TeX to print the entity's name and its arguments on the left margin and print the category next to the right margin. In both output formats, the body of the definition is indented. Also, the name of the entity is entered into the appropriate index: `@deffn' enters the name into the index of functions, `@defvr' enters it into the index of variables, and so on (*note Predefined Indices::). A manual need not and should not contain more than one definition for a given name. An appendix containing a summary should use `@table' rather than the definition commands. * Menu: * Def Cmd Template:: Writing descriptions using definition commands. * Def Cmd Continuation Lines:: Continuing the heading over source lines. * Optional Arguments:: Handling optional and repeated arguments. * deffnx:: Group two or more `first' lines. * Def Cmds in Detail:: Reference for all the definition commands. * Def Cmd Conventions:: Conventions for writing definitions. * Sample Function Definition:: An example.  File: texinfo, Node: Def Cmd Template, Next: Def Cmd Continuation Lines, Up: Definition Commands 16.1 The Template for a Definition ================================== The `@deffn' command is used for definitions of entities that resemble functions. To write a definition using the `@deffn' command, write the `@deffn' command at the beginning of a line and follow it on the same line by the category of the entity, the name of the entity itself, and its arguments (if any). Then write the body of the definition on succeeding lines. (You may embed examples in the body.) Finally, end the definition with an `@end deffn' command written on a line of its own. The other definition commands follow the same format: a line with the `@def...' command and whatever arguments are appropriate for that command; the body of the definition; and a corresponding `@end' line. The template for a definition looks like this: @deffn CATEGORY NAME ARGUMENTS... BODY-OF-DEFINITION @end deffn For example, @deffn Command forward-word count This command moves point forward @var{count} words (or backward if @var{count} is negative). ... @end deffn produces -- Command: forward-word count This command moves point forward COUNT words (or backward if COUNT is negative). ... Capitalize the category name like a title. If the name of the category contains spaces, as in the phrase `Interactive Command', enclose it in braces. For example: @deffn {Interactive Command} isearch-forward ... @end deffn Otherwise, the second word will be mistaken for the name of the entity. As a general rule, when any of the arguments in the heading line _except_ the last one are more than one word, you need to enclose them in braces. This may also be necessary if the text contains commands, for example, `{declaraci@'on}' if you are writing in Spanish. Some of the definition commands are more general than others. The `@deffn' command, for example, is the general definition command for functions and the like--for entities that may take arguments. When you use this command, you specify the category to which the entity belongs. Three predefined, specialized variations (`@defun', `@defmac', and `@defspec') specify the category for you: "Function", "Macro", and "Special Form" respectively. (In Lisp, a special form is an entity much like a function.) Similarly, the general `@defvr' command is accompanied by several specialized variations for describing particular kinds of variables. *Note Sample Function Definition::, for a detailed example of a function definition, including the use of `@example' inside the definition. Unfortunately, due to implementation difficulties, macros are not expanded in `@deffn' and all the other definition commands.  File: texinfo, Node: Def Cmd Continuation Lines, Next: Optional Arguments, Prev: Def Cmd Template, Up: Definition Commands 16.2 Definition Command Continuation Lines ========================================== The heading line of a definition command can get very long. Therefore, Texinfo has a special syntax allowing them to be continued over multiple lines of the source file: a lone `@' at the end of each line to be continued. Here's an example: @defun fn-name @ arg1 arg2 arg3 This is the basic continued defun. @end defun produces: -- Function: fn-name arg1 arg2 arg3 This is the basic continued defun. As you can see, the continued lines are combined, as if they had been typed on one source line. Although this example only shows a one-line continuation, continuations may extend over any number of lines; simply put an `@' at the end of each line to be continued. The `@' character does not have to be the last character on the physical line: whitespace is allowed (and ignored) afterwards. In general, any number of spaces or tabs around the `@' continuation character, both on the line with the `@' and on the continued line, are collapsed into a single space. There is one exception: the Texinfo processors will not fully collapse whitespace around a continuation inside braces. For example: @deffn {Category @ Name} ... The output (not shown) has excess space between `Category' and `Name'. In this case, simply elide any unwanted whitespace in your input, or put the continuation `@' outside braces. `@' does not (currently) function as a continuation character in _any_ other context. Ordinarily, `@' followed by a whitespace character (space, tab, newline) produces a normal interword space (*note Multiple Spaces::).  File: texinfo, Node: Optional Arguments, Next: deffnx, Prev: Def Cmd Continuation Lines, Up: Definition Commands 16.3 Optional and Repeated Arguments ==================================== Some entities take optional or repeated arguments, which may be specified by a distinctive glyph that uses square brackets and ellipses. For example, a special form often breaks its argument list into separate arguments in more complicated ways than a straightforward function. An argument enclosed within square brackets is optional. Thus, [OPTIONAL-ARG] means that OPTIONAL-ARG is optional. An argument followed by an ellipsis is optional and may be repeated more than once. Thus, REPEATED-ARGS`...' stands for zero or more arguments. Parentheses are used when several arguments are grouped into additional levels of list structure in Lisp. Here is the `@defspec' line of an example of an imaginary special form: -- Special Form: foobar (VAR [FROM TO [INC]]) BODY... In this example, the arguments FROM and TO are optional, but must both be present or both absent. If they are present, INC may optionally be specified as well. These arguments are grouped with the argument VAR into a list, to distinguish them from BODY, which includes all remaining elements of the form. In a Texinfo source file, this `@defspec' line is written like this (except it would not be split over two lines, as it is in this example). @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} The function is listed in the Command and Variable Index under `foobar'.  File: texinfo, Node: deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands 16.4 Two or More `First' Lines ============================== To create two or more `first' or header lines for a definition, follow the first `@deffn' line by a line beginning with `@deffnx'. The `@deffnx' command works exactly like `@deffn' except that it does not generate extra vertical white space between it and the preceding line. For example, @deffn {Interactive Command} isearch-forward @deffnx {Interactive Command} isearch-backward These two search commands are similar except ... @end deffn produces -- Interactive Command: isearch-forward -- Interactive Command: isearch-backward These two search commands are similar except ... Each definition command has an `x' form: `@defunx', `@defvrx', `@deftypefunx', etc. The `x' forms work similarly to `@itemx' (*note itemx::).  File: texinfo, Node: Def Cmds in Detail, Next: Def Cmd Conventions, Prev: deffnx, Up: Definition Commands 16.5 The Definition Commands ============================ Texinfo provides more than a dozen definition commands, all of which are described in this section. The definition commands automatically enter the name of the entity in the appropriate index: for example, `@deffn', `@defun', and `@defmac' enter function names in the index of functions; `@defvr' and `@defvar' enter variable names in the index of variables. Although the examples that follow mostly illustrate Lisp, the commands can be used for other programming languages. * Menu: * Functions Commands:: Commands for functions and similar entities. * Variables Commands:: Commands for variables and similar entities. * Typed Functions:: Commands for functions in typed languages. * Typed Variables:: Commands for variables in typed languages. * Data Types:: The definition command for data types. * Abstract Objects:: Commands for object-oriented programming.  File: texinfo, Node: Functions Commands, Next: Variables Commands, Up: Def Cmds in Detail 16.5.1 Functions and Similar Entities ------------------------------------- This section describes the commands for describing functions and similar entities: `@deffn CATEGORY NAME ARGUMENTS...' The `@deffn' command is the general definition command for functions, interactive commands, and similar entities that may take arguments. You must choose a term to describe the category of entity being defined; for example, "Function" could be used if the entity is a function. The `@deffn' command is written at the beginning of a line and is followed on the same line by the category of entity being described, the name of this particular entity, and its arguments, if any. Terminate the definition with `@end deffn' on a line of its own. For example, here is a definition: @deffn Command forward-char nchars Move point forward @var{nchars} characters. @end deffn This shows a rather terse definition for a "command" named `forward-char' with one argument, NCHARS. `@deffn' and prints argument names such as NCHARS in slanted type in the printed output, because we think of these names as metasyntactic variables--they stand for the actual argument values. Within the text of the description, however, write an argument name explicitly with `@var' to refer to the value of the argument. In the example above, we used `@var{nchars}' in this way. In the unusual case when an argument name contains `--', or another character sequence which is treated specially (*note Conventions::), use `@var' around the argument. This causes the name to be printed in slanted typewriter, instead of the regular slanted font, exactly as input. The template for `@deffn' is: @deffn CATEGORY NAME ARGUMENTS... BODY-OF-DEFINITION @end deffn `@defun NAME ARGUMENTS...' The `@defun' command is the definition command for functions. `@defun' is equivalent to `@deffn Function ...'. Terminate the definition with `@end defun' on a line of its own. Thus, the template is: @defun FUNCTION-NAME ARGUMENTS... BODY-OF-DEFINITION @end defun `@defmac NAME ARGUMENTS...' The `@defmac' command is the definition command for macros. `@defmac' is equivalent to `@deffn Macro ...' and works like `@defun'. `@defspec NAME ARGUMENTS...' The `@defspec' command is the definition command for special forms. (In Lisp, a special form is an entity much like a function, *note Special Forms: (elisp)Special Forms.) `@defspec' is equivalent to `@deffn {Special Form} ...' and works like `@defun'. All these commands create entries in the index of functions.  File: texinfo, Node: Variables Commands, Next: Typed Functions, Prev: Functions Commands, Up: Def Cmds in Detail 16.5.2 Variables and Similar Entities ------------------------------------- Here are the commands for defining variables and similar entities: `@defvr CATEGORY NAME' The `@defvr' command is a general definition command for something like a variable--an entity that records a value. You must choose a term to describe the category of entity being defined; for example, "Variable" could be used if the entity is a variable. Write the `@defvr' command at the beginning of a line and follow it on the same line by the category of the entity and the name of the entity. Capitalize the category name like a title. If the name of the category contains spaces, as in the name "User Option", enclose it in braces. Otherwise, the second word will be mistaken for the name of the entity. For example, @defvr {User Option} fill-column This buffer-local variable specifies the maximum width of filled lines. ... @end defvr Terminate the definition with `@end defvr' on a line of its own. The template is: @defvr CATEGORY NAME BODY-OF-DEFINITION @end defvr `@defvr' creates an entry in the index of variables for NAME. `@defvar NAME' The `@defvar' command is the definition command for variables. `@defvar' is equivalent to `@defvr Variable ...'. For example: @defvar kill-ring ... @end defvar The template is: @defvar NAME BODY-OF-DEFINITION @end defvar `@defvar' creates an entry in the index of variables for NAME. `@defopt NAME' The `@defopt' command is the definition command for "user options", i.e., variables intended for users to change according to taste; Emacs has many such (*note Variables: (emacs)Variables.). `@defopt' is equivalent to `@defvr {User Option} ...' and works like `@defvar'. It creates an entry in the index of variables.  File: texinfo, Node: Typed Functions, Next: Typed Variables, Prev: Variables Commands, Up: Def Cmds in Detail 16.5.3 Functions in Typed Languages ----------------------------------- The `@deftypefn' command and its variations are for describing functions in languages in which you must declare types of variables and functions, such as C and C++. `@deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS...' The `@deftypefn' command is the general definition command for functions and similar entities that may take arguments and that are typed. The `@deftypefn' command is written at the beginning of a line and is followed on the same line by the category of entity being described, the type of the returned value, the name of this particular entity, and its arguments, if any. For example, @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar}) ... @end deftypefn (where the text before the "...", shown above as two lines, would actually be a single line in a real Texinfo file) produces the following in Info: -- Library Function: int foobar (int FOO, float BAR) ... This means that `foobar' is a "library function" that returns an `int', and its arguments are FOO (an `int') and BAR (a `float'). Since in typed languages, the actual names of the arguments are typically scattered among data type names and keywords, Texinfo cannot find them without help. You can either (a) write everything as straight text, and it will be printed in slanted type; (b) use `@var' for the variable names, which will uppercase the variable names in Info and use the slanted typewriter font in printed output; (c) use `@var' for the variable names and `@code' for the type names and keywords, which will be dutifully obeyed. The template for `@deftypefn' is: @deftypefn CATEGORY DATA-TYPE NAME ARGUMENTS ... BODY-OF-DESCRIPTION @end deftypefn Note that if the CATEGORY or DATA TYPE is more than one word then it must be enclosed in braces to make it a single argument. If you are describing a procedure in a language that has packages, such as Ada, you might consider using `@deftypefn' in a manner somewhat contrary to the convention described in the preceding paragraphs. For example: @deftypefn stacks private push @ (@var{s}:in out stack; @ @var{n}:in integer) ... @end deftypefn (The `@deftypefn' arguments are shown using continuations (*note Def Cmd Continuation Lines::), but could be on a single line in a real Texinfo file.) In this instance, the procedure is classified as belonging to the package `stacks' rather than classified as a `procedure' and its data type is described as `private'. (The name of the procedure is `push', and its arguments are S and N.) `@deftypefn' creates an entry in the index of functions for NAME. `@deftypefun DATA-TYPE NAME ARGUMENTS...' The `@deftypefun' command is the specialized definition command for functions in typed languages. The command is equivalent to `@deftypefn Function ...'. The template is: @deftypefun TYPE NAME ARGUMENTS... BODY-OF-DESCRIPTION @end deftypefun `@deftypefun' creates an entry in the index of functions for NAME.  File: texinfo, Node: Typed Variables, Next: Data Types, Prev: Typed Functions, Up: Def Cmds in Detail 16.5.4 Variables in Typed Languages ----------------------------------- Variables in typed languages are handled in a manner similar to functions in typed languages. *Note Typed Functions::. The general definition command `@deftypevr' corresponds to `@deftypefn' and the specialized definition command `@deftypevar' corresponds to `@deftypefun'. `@deftypevr CATEGORY DATA-TYPE NAME' The `@deftypevr' command is the general definition command for something like a variable in a typed language--an entity that records a value. You must choose a term to describe the category of the entity being defined; for example, "Variable" could be used if the entity is a variable. The `@deftypevr' command is written at the beginning of a line and is followed on the same line by the category of the entity being described, the data type, and the name of this particular entity. For example: @deftypevr {Global Flag} int enable ... @end deftypevr produces the following in Info: -- Global Flag: int enable ... The template is: @deftypevr CATEGORY DATA-TYPE NAME BODY-OF-DESCRIPTION @end deftypevr `@deftypevar DATA-TYPE NAME' The `@deftypevar' command is the specialized definition command for variables in typed languages. `@deftypevar' is equivalent to `@deftypevr Variable ...'. The template is: @deftypevar DATA-TYPE NAME BODY-OF-DESCRIPTION @end deftypevar These commands create entries in the index of variables.  File: texinfo, Node: Data Types, Next: Abstract Objects, Prev: Typed Variables, Up: Def Cmds in Detail 16.5.5 Data Types ----------------- Here is the command for data types: `@deftp CATEGORY NAME ATTRIBUTES...' The `@deftp' command is the generic definition command for data types. The command is written at the beginning of a line and is followed on the same line by the category, by the name of the type (which is a word like `int' or `float'), and then by names of attributes of objects of that type. Thus, you could use this command for describing `int' or `float', in which case you could use `data type' as the category. (A data type is a category of certain objects for purposes of deciding which operations can be performed on them.) In Lisp, for example, "pair" names a particular data type, and an object of that type has two slots called the CAR and the CDR. Here is how you would write the first line of a definition of `pair'. @deftp {Data type} pair car cdr ... @end deftp The template is: @deftp CATEGORY NAME-OF-TYPE ATTRIBUTES... BODY-OF-DEFINITION @end deftp `@deftp' creates an entry in the index of data types.  File: texinfo, Node: Abstract Objects, Prev: Data Types, Up: Def Cmds in Detail 16.5.6 Object-Oriented Programming ---------------------------------- Here are the commands for formatting descriptions about abstract objects, such as are used in object-oriented programming. A class is a defined type of abstract object. An instance of a class is a particular object that has the type of the class. An instance variable is a variable that belongs to the class but for which each instance has its own value. * Menu: * Variables: Object-Oriented Variables. * Methods: Object-Oriented Methods.  File: texinfo, Node: Object-Oriented Variables, Next: Object-Oriented Methods, Up: Abstract Objects 16.5.6.1 Object-Oriented Variables .................................. These commands allow you to define different sorts of variables in object-oriented programming languages. `@defcv CATEGORY CLASS NAME' The `@defcv' command is the general definition command for variables associated with classes in object-oriented programming. The `@defcv' command is followed by three arguments: the category of thing being defined, the class to which it belongs, and its name. For instance: @defcv {Class Option} Window border-pattern ... @end defcv produces: -- Class Option of Window: border-pattern ... `@defcv' creates an entry in the index of variables. `@deftypecv CATEGORY CLASS DATA-TYPE NAME' The `@deftypecv' command is the definition command for typed class variables in object-oriented programming. It is analogous to `@defcv' with the addition of the DATA-TYPE parameter to specify the type of the instance variable. Ordinarily, the data type is a programming language construct that should be marked with `@code'. For instance: @deftypecv {Class Option} Window @code{int} border-pattern ... @end deftypecv produces: -- Class Option of Window: `int' border-pattern ... `@deftypecv' creates an entry in the index of variables. `@defivar CLASS NAME' The `@defivar' command is the definition command for instance variables in object-oriented programming. `@defivar' is equivalent to `@defcv {Instance Variable} ...'. For instance: @defivar Window border-pattern ... @end defivar produces: -- Instance Variable of Window: border-pattern ... `@defivar' creates an entry in the index of variables. `@deftypeivar CLASS DATA-TYPE NAME' The `@deftypeivar' command is the definition command for typed instance variables in object-oriented programming. It is analogous to `@defivar' with the addition of the DATA-TYPE parameter to specify the type of the instance variable. Ordinarily, the data type is a programming language construct that should be marked with `@code'. For instance: @deftypeivar Window @code{int} border-pattern ... @end deftypeivar produces: -- Instance Variable of Window: `int' border-pattern ... `@deftypeivar' creates an entry in the index of variables.  File: texinfo, Node: Object-Oriented Methods, Prev: Object-Oriented Variables, Up: Abstract Objects 16.5.6.2 Object-Oriented Methods ................................ These commands allow you to define different sorts of function-like entities resembling methods in object-oriented programming languages. These entities take arguments, as functions do, but are associated with particular classes of objects. `@defop CATEGORY CLASS NAME ARGUMENTS...' The `@defop' command is the general definition command for these method-like entities. For example, some systems have constructs called "wrappers" that are associated with classes as methods are, but that act more like macros than like functions. You could use `@defop Wrapper' to describe one of these. Sometimes it is useful to distinguish methods and "operations". You can think of an operation as the specification for a method. Thus, a window system might specify that all window classes have a method named `expose'; we would say that this window system defines an `expose' operation on windows in general. Typically, the operation has a name and also specifies the pattern of arguments; all methods that implement the operation must accept the same arguments, since applications that use the operation do so without knowing which method will implement it. Often it makes more sense to document operations than methods. For example, window application developers need to know about the `expose' operation, but need not be concerned with whether a given class of windows has its own method to implement this operation. To describe this operation, you would write: @defop Operation windows expose The `@defop' command is written at the beginning of a line and is followed on the same line by the overall name of the category of operation, the name of the class of the operation, the name of the operation, and its arguments, if any. The template is: @defop CATEGORY CLASS NAME ARGUMENTS... BODY-OF-DEFINITION @end defop `@defop' creates an entry, such as ``expose' on `windows'', in the index of functions. `@deftypeop CATEGORY CLASS DATA-TYPE NAME ARGUMENTS...' The `@deftypeop' command is the definition command for typed operations in object-oriented programming. It is similar to `@defop' with the addition of the DATA-TYPE parameter to specify the return type of the method. `@deftypeop' creates an entry in the index of functions. `@defmethod CLASS NAME ARGUMENTS...' The `@defmethod' command is the definition command for methods in object-oriented programming. A method is a kind of function that implements an operation for a particular class of objects and its subclasses. `@defmethod' is equivalent to `@defop Method ...'. The command is written at the beginning of a line and is followed by the name of the class of the method, the name of the method, and its arguments, if any. For example: @defmethod `bar-class' bar-method argument ... @end defmethod illustrates the definition for a method called `bar-method' of the class `bar-class'. The method takes an argument. `@defmethod' creates an entry in the index of functions. `@deftypemethod CLASS DATA-TYPE NAME ARGUMENTS...' The `@deftypemethod' command is the definition command for methods in object-oriented typed languages, such as C++ and Java. It is similar to the `@defmethod' command with the addition of the DATA-TYPE parameter to specify the return type of the method. `@deftypemethod' creates an entry in the index of functions.  File: texinfo, Node: Def Cmd Conventions, Next: Sample Function Definition, Prev: Def Cmds in Detail, Up: Definition Commands 16.6 Conventions for Writing Definitions ======================================== When you write a definition using `@deffn', `@defun', or one of the other definition commands, please take care to use arguments that indicate the meaning, as with the COUNT argument to the `forward-word' function. Also, if the name of an argument contains the name of a type, such as INTEGER, take care that the argument actually is of that type.  File: texinfo, Node: Sample Function Definition, Prev: Def Cmd Conventions, Up: Definition Commands 16.7 A Sample Function Definition ================================= A function definition uses the `@defun' and `@end defun' commands. The name of the function follows immediately after the `@defun' command and it is followed, on the same line, by the parameter list. Here is a definition from *note Calling Functions: (elisp)Calling Functions. -- Function: apply function &rest arguments `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but with one difference: the last of ARGUMENTS is a list of arguments to give to FUNCTION, rather than a single argument. We also say that this list is "appended" to the other arguments. `apply' returns the result of calling FUNCTION. As with `funcall', FUNCTION must either be a Lisp function or a primitive function; special forms and macros do not make sense in `apply'. (setq f 'list) => list (apply f 'x 'y 'z) error--> Wrong type argument: listp, z (apply '+ 1 2 '(3 4)) => 10 (apply '+ '(1 2 3 4)) => 10 (apply 'append '((a b c) nil (x y z) nil)) => (a b c x y z) An interesting example of using `apply' is found in the description of `mapcar'. In the Texinfo source file, this example looks like this: @defun apply function &rest arguments @code{apply} calls @var{function} with @var{arguments}, just like @code{funcall} but with one difference: the last of @var{arguments} is a list of arguments to give to @var{function}, rather than a single argument. We also say that this list is @dfn{appended} to the other arguments. @code{apply} returns the result of calling @var{function}. As with @code{funcall}, @var{function} must either be a Lisp function or a primitive function; special forms and macros do not make sense in @code{apply}. @example (setq f 'list) @result{} list (apply f 'x 'y 'z) @error{} Wrong type argument: listp, z (apply '+ 1 2 '(3 4)) @result{} 10 (apply '+ '(1 2 3 4)) @result{} 10 (apply 'append '((a b c) nil (x y z) nil)) @result{} (a b c x y z) @end example An interesting example of using @code{apply} is found in the description of @code{mapcar}. @end defun In this manual, this function is listed in the Command and Variable Index under `apply'. Ordinary variables and user options are described using a format like that for functions except that variables do not take arguments.  File: texinfo, Node: Conditionals, Next: Internationalization, Prev: Definition Commands, Up: Top 17 Conditionally Visible Text ***************************** The "conditional commands" allow you to use different text for different output formats, or for general conditions that you define. For example, you can use them to specify different text for the printed manual and the Info output. The conditional commands comprise the following categories. * Commands specific to an output format (Info, TeX, HTML, ...). * Commands specific to any output format _other_ than a given one (not Info, not TeX, ...). * `Raw' formatter text for any output format, passed straight through with no interpretation of @-commands. * Format-independent variable substitutions, and testing if a variable is set or clear. * Menu: * Conditional Commands:: Text for a given format. * Conditional Not Commands:: Text for any format other than a given one. * Raw Formatter Commands:: Using raw formatter commands. * set clear value:: Variable tests and substitutions. * Conditional Nesting:: Using conditionals inside conditionals.  File: texinfo, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals 17.1 Conditional Commands ========================= Texinfo has an `@ifFORMAT' environment for each output format, to allow conditional inclusion of text for a particular output format. `@ifinfo' begins segments of text that should be ignored by TeX when it typesets the printed manual, and by `makeinfo' when not producing Info output. The segment of text appears only in the Info file and, for historical compatibility, the plain text output. The environments for the other formats are analogous: `@ifdocbook ... @end ifdocbook' Text to appear only in the Docbook output. `@ifhtml ... @end ifhtml' Text to appear only in the HTML output. `@ifplaintext ... @end ifplaintext' Text to appear only in the plain text output. `@iftex ... @end iftex' Text to appear only in the printed manual. `@ifxml ... @end ifxml' Text to appear only in the XML output. The `@if...' and `@end if...' commands must appear on lines by themselves in your source file. Here is an example showing all these conditionals: @iftex This text will appear only in the printed manual. @end iftex @ifinfo However, this text will appear only in Info and plain text. @end ifinfo @ifhtml And this text will only appear in HTML. @end ifhtml @ifplaintext Whereas this text will only appear in plain text. @end ifplaintext @ifxml Notwithstanding that this will only appear in XML. @end ifxml @ifdocbook Nevertheless, this will only appear in Docbook. @end ifdocbook The preceding example produces the following line: However, this text will appear only in Info and plain text. Notice that you only see one of the input lines, depending on which version of the manual you are reading.  File: texinfo, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals 17.2 Conditional Not Commands ============================= You can specify text to be included in any output format _other_ than a given one with the `@ifnot...' environments: @ifnotdocbook ... @end ifnotdocbook @ifnothtml ... @end ifnothtml @ifnotinfo ... @end ifnotinfo @ifnotplaintext ... @end ifnotplaintext @ifnottex ... @end ifnottex @ifnotxml ... @end ifnotxml The `@ifnot...' command and the `@end' command must appear on lines by themselves in your actual source file. If the output file is being made in the given format, the region is _ignored_. Otherwise, it is included. There is one exception (for historical compatibility): `@ifnotinfo' text is omitted for both Info and plain text output, not just Info. To specify text which appears only in Info and not in plain text, use `@ifnotplaintext', like this: @ifinfo @ifnotplaintext This will be in Info, but not plain text. @end ifnotplaintext @end ifinfo The regions delimited by these commands are ordinary Texinfo source as with `@iftex', not raw formatter source as with `@tex' (*note Raw Formatter Commands::).  File: texinfo, Node: Raw Formatter Commands, Next: set clear value, Prev: Conditional Not Commands, Up: Conditionals 17.3 Raw Formatter Commands =========================== Inside a region delineated by `@iftex' and `@end iftex', you can embed some raw TeX commands. The Texinfo processors will ignore such a region unless TeX output is being produced. You can write the TeX commands as you would write them in a normal TeX file, except that you must replace the `\' used by TeX with an `@'. For example, in the `@titlepage' section of a Texinfo file, you can use the TeX command `@vskip' to format the copyright page. (The `@titlepage' command causes Info to ignore the region automatically, as it does with the `@iftex' command.) However, most features of plain TeX will not work within `@iftex', as they are overridden by Texinfo features. The purpose of `@iftex' is to provide conditional processing for the Texinfo source, not provide access to underlying formatting features. You can enter plain TeX completely, and use `\' in the TeX commands, by delineating a region with the `@tex' and `@end tex' commands. All plain TeX commands and category codes are restored within an `@tex' region. The sole exception is that the `@' character still introduces a command, so that `@end tex' can be recognized properly. As with `@iftex', Texinfo processors will ignore such a region unless TeX output is being produced. In complex cases, you may wish to define new TeX macros within `@tex'. You must use `\gdef' to do this, not `\def', because `@tex' regions are processed in a TeX group. As an example, here is a mathematical expression written in plain TeX: @tex $$ \chi^2 = \sum_{i=1}^N \left (y_i - (a + b x_i) \over \sigma_i\right)^2 $$ @end tex The output of this example will appear only in a printed manual. If you are reading this in Info, you will not see the equation that appears in the printed manual. Analogously, you can use `@ifhtml ... @end ifhtml' to delimit a region to be included in HTML output only, and `@html ... @end html' for a region of raw HTML. Likewise, you can use `@ifxml ... @end ifxml' to delimit a region to be included in XML output only, and `@xml ... @end xml' for a region of raw XML. Again likewise, you can use `@ifdocbook ... @end ifdocbook' to delimit a region to be included in Docbook output only, and `@docbook ... @end docbook' for a region of raw Docbook. In all cases, the exception to the raw processing is that `@' is still an escape character, so the `@end' command can be recognized.  File: texinfo, Node: set clear value, Next: Conditional Nesting, Prev: Raw Formatter Commands, Up: Conditionals 17.4 `@set', `@clear', and `@value' =================================== You can direct the Texinfo formatting commands to format or ignore parts of a Texinfo file with the `@set', `@clear', `@ifset', and `@ifclear' commands. Here are brief descriptions of these commands, see the following sections for more details: `@set FLAG [VALUE]' Set the variable FLAG, to the optional VALUE if specified. `@clear FLAG' Undefine the variable FLAG, whether or not it was previously defined. `@ifset FLAG' If FLAG is set, text through the next `@end ifset' command is formatted. If FLAG is clear, text through the following `@end ifset' command is ignored. `@ifclear FLAG' If FLAG is set, text through the next `@end ifclear' command is ignored. If FLAG is clear, text through the following `@end ifclear' command is formatted. * Menu: * set value:: Expand a flag variable to a string. * ifset ifclear:: Format a region if a flag is set. * value Example:: An easy way to update edition information.  File: texinfo, Node: set value, Next: ifset ifclear, Up: set clear value 17.4.1 `@set' and `@value' -------------------------- You use the `@set' command to specify a value for a flag, which is later expanded by the `@value' command. A "flag" (aka "variable") is an identifier. It is best to use only letters and numerals in a flag name, not `-' or `_'--they will work in some contexts, but not all, due to limitations in TeX. The value is the remainder of the input line, and can contain anything. Write the `@set' command like this: @set foo This is a string. This sets the value of the flag `foo' to "This is a string.". The Texinfo formatters then replace an `@value{FLAG}' command with the string to which FLAG is set. Thus, when `foo' is set as shown above, the Texinfo formatters convert this: @value{foo} to this: This is a string. You can write an `@value' command within a paragraph; but you must write an `@set' command on a line of its own. If you write the `@set' command like this: @set foo without specifying a string, the value of `foo' is the empty string. If you clear a previously set flag with `@clear FLAG', a subsequent `@value{flag}' command will report an error. For example, if you set `foo' as follows: @set howmuch very, very, very then the formatters transform It is a @value{howmuch} wet day. into It is a very, very, very wet day. If you write @clear howmuch then the formatters transform It is a @value{howmuch} wet day. into It is a {No value for "howmuch"} wet day.  File: texinfo, Node: ifset ifclear, Next: value Example, Prev: set value, Up: set clear value 17.4.2 `@ifset' and `@ifclear' ------------------------------ When a FLAG is set, the Texinfo formatting commands format text between subsequent pairs of `@ifset FLAG' and `@end ifset' commands. When the FLAG is cleared, the Texinfo formatting commands do _not_ format the text. `@ifclear' operates analogously. Write the conditionally formatted text between `@ifset FLAG' and `@end ifset' commands, like this: @ifset FLAG CONDITIONAL-TEXT @end ifset For example, you can create one document that has two variants, such as a manual for a `large' and `small' model: You can use this machine to dig up shrubs without hurting them. @set large @ifset large It can also dig up fully grown trees. @end ifset Remember to replant promptly ... In the example, the formatting commands will format the text between `@ifset large' and `@end ifset' because the `large' flag is set. When FLAG is cleared, the Texinfo formatting commands do _not_ format the text between `@ifset FLAG' and `@end ifset'; that text is ignored and does not appear in either printed or Info output. For example, if you clear the flag of the preceding example by writing an `@clear large' command after the `@set large' command (but before the conditional text), then the Texinfo formatting commands ignore the text between the `@ifset large' and `@end ifset' commands. In the formatted output, that text does not appear; in both printed and Info output, you see only the lines that say, "You can use this machine to dig up shrubs without hurting them. Remember to replant promptly ...". If a flag is cleared with an `@clear FLAG' command, then the formatting commands format text between subsequent pairs of `@ifclear' and `@end ifclear' commands. But if the flag is set with `@set FLAG', then the formatting commands do _not_ format text between an `@ifclear' and an `@end ifclear' command; rather, they ignore that text. An `@ifclear' command looks like this: @ifclear FLAG  File: texinfo, Node: value Example, Prev: ifset ifclear, Up: set clear value 17.4.3 `@value' Example ----------------------- You can use the `@value' command to minimize the number of places you need to change when you record an update to a manual. *Note GNU Sample Texts::, for the full text of an example of using this to work with Automake distributions. This example is adapted from *note Overview: (make)Top. 1. Set the flags: @set EDITION 0.35 Beta @set VERSION 3.63 Beta @set UPDATED 14 August 1992 @set UPDATE-MONTH August 1992 2. Write text for the `@copying' section (*note copying::): @copying This is Edition @value{EDITION}, last updated @value{UPDATED}, of @cite{The GNU Make Manual}, for @code{make}, version @value{VERSION}. Copyright ... Permission is granted ... @end copying 3. Write text for the title page, for people reading the printed manual: @titlepage @title GNU Make @subtitle A Program for Directing Recompilation @subtitle Edition @value{EDITION}, ... @subtitle @value{UPDATE-MONTH} @page @insertcopying ... @end titlepage (On a printed cover, a date listing the month and the year looks less fussy than a date listing the day as well as the month and year.) 4. Write text for the Top node, for people reading the Info file: @ifnottex @node Top @top Make @insertcopying ... @end ifnottex After you format the manual, the `@value' constructs have been expanded, so the output contains text like this: This is Edition 0.35 Beta, last updated 14 August 1992, of `The GNU Make Manual', for `make', Version 3.63 Beta. When you update the manual, you change only the values of the flags; you do not need to edit the three sections.  File: texinfo, Node: Conditional Nesting, Prev: set clear value, Up: Conditionals 17.5 Conditional Nesting ======================== Conditionals can be nested; however, the details are a little tricky. The difficulty comes with failing conditionals, such as `@ifhtml' when HTML is not being produced, where the included text is to be ignored. However, it is not to be _completely_ ignored, since it is useful to have one `@ifset' inside another, for example--that is a way to include text only if two conditions are met. Here's an example: @ifset somevar @ifset anothervar Both somevar and anothervar are set. @end ifset @ifclear anothervar Somevar is set, anothervar is not. @end ifclear @end ifset Technically, Texinfo requires that for a failing conditional, the ignored text must be properly nested with respect to that failing conditional. Unfortunately, it's not always feasible to check that _all_ conditionals are properly nested, because then the processors could have to fully interpret the ignored text, which defeats the purpose of the command. Here's an example illustrating these rules: @ifset a @ifset b @ifclear ok - ok, ignored @end junky - ok, ignored @end ifset @c WRONG - missing @end ifset. Finally, as mentioned above, all conditional commands must be on lines by themselves, with no text (even spaces) before or after. Otherwise, the processors cannot reliably determine which commands to consider for nesting purposes.  File: texinfo, Node: Internationalization, Next: Defining New Texinfo Commands, Prev: Conditionals, Up: Top 18 Internationalization *********************** Texinfo has some support for writing in languages other than English, although this area still needs considerable work. For a list of the various accented and special characters Texinfo supports, see *note Inserting Accents::. * Menu: * documentlanguage:: Declaring the current language. * documentencoding:: Declaring the input encoding.  File: texinfo, Node: documentlanguage, Next: documentencoding, Up: Internationalization 18.1 `@documentlanguage LL[_CC]': Set the Document Language =========================================================== The `@documentlanguage' command declares the current document locale. Write it on a line by itself, near the beginning of the file, but after `@setfilename' (*note `@setfilename': setfilename.): @documentlanguage LL[_CC] Include a two-letter ISO 639-2 language code (LL) following the command name, optionally followed by an underscore and two-letter ISO 3166 two-letter country code (CC). If you have a multilingual document, the intent is to be able to use this command multiple times, to declare each language change. If the command is not used at all, the default is `en_US' for US English. As with GNU Gettext (*note Top: (gettext)Top.), if the country code is omitted, the main dialect is assumed where possible. For example, `de' is equivalent to `de_DE' (German as spoken in Germany). For Info and other online output, this command changes the translation of various "document strings" such as "see" in cross-references (*note Cross References::), "Function' in defuns (*note Definition Commands::), and so on. Some strings, such as "Node:", "Next:", "Menu:", etc., are keywords in Info output, so are not translated there; they are translated in other output formats. For TeX, this command causes a file `txi-LOCALE.tex' to be read (if it exists). If `@setdocumentlanguage' argument contains the optional `_CC' suffix, this is tried first. For example, with `@setdocumentlanguage de_DE', TeX first looks for `txi-de_DE.tex', then `txi-de.tex'. Such a `txi-*' file is intended to redefine the various English words used in TeX output, such as `Chapter', `See', and so on. We are aware that individual words like these cannot always be translated in isolation, and that a very different strategy would be required for ideographic (among other) scripts. Help in improving Texinfo's language support is welcome. It would also be desirable for this command to also change TeX's ideas of the current hyphenation patterns (via the TeX primitive `\language'), but this is unfortunately not currently implemented. In September 2006, the W3C Internationalization Activity released a new recommendation for specifying languages: `http://www.rfc-editor.org/rfc/bcp/bcp47.txt'. When Gettext supports this new scheme, Texinfo will too. Since the lists of language codes and country codes are updated relatively frequently, we don't attempt to list them here. The valid language codes are on the official home page for ISO 639, `http://www.loc.gov/standards/iso639-2/'. The country codes and the official web site for ISO 3166 can be found via `http://en.wikipedia.org/wiki/ISO_3166'.  File: texinfo, Node: documentencoding, Prev: documentlanguage, Up: Internationalization 18.2 `@documentencoding ENC': Set Input Encoding ================================================ The `@documentencoding' command declares the input document encoding. Write it on a line by itself, with a valid encoding specification following, near the beginning of the file but after `@setfilename' (*note `@setfilename': setfilename.): @documentencoding ENC At present, Texinfo supports only these encodings: `US-ASCII' This has no particular effect, but it's included for completeness. `UTF-8' The vast global character encoding, expressed in 8-bit bytes. The Texinfo processors have no deep knowledge of Unicode; for the most part, they just pass along the input they are given to the output. `ISO-8859-1' `ISO-8859-15' `ISO-8859-2' These specify the standard encodings for Western European (the first two) and Eastern European languages (the third), respectively. ISO 8859-15 replaces some little-used characters from 8859-1 (e.g., precomposed fractions) with more commonly needed ones, such as the Euro symbol (Euro ). A full description of the encodings is beyond our scope here; one useful reference is `http://czyborra.com/charsets/iso8859.html'. `koi8-r' This is the commonly used encoding for the Russian language. `koi8-u' This is the commonly used encoding for the Ukrainian language. Specifying an encoding ENC has the following effects: In Info output, unless the option `--disable-encoding' is given to `makeinfo', a so-called `Local Variables' section (*note File Variables: (emacs)File Variables.) is output including ENC. This allows Info readers to set the encoding appropriately. Local Variables: coding: ENC End: Also, in Info and plain text output (barring `--disable-encoding'), accent constructs and special characters, such as `@'e', are output as the actual 8-bit character in the given encoding. In HTML output, a `' tag is output, in the `' section of the HTML, that specifies ENC. Web servers and browsers cooperate to use this information so the correct encoding is used to display the page, if supported by the system. In split HTML output, if `--transliterate-file-names' is given (*note HTML Xref 8-bit Character Expansion::), the names of HTML files are formed by transliteration of the corresponding node names, using the specified encoding. In XML and Docbook output, the given document encoding is written in the output file as usual with those formats. In TeX output, the characters which are supported in the standard Computer Modern fonts are output accordingly. (For example, this means using constructed accents rather than precomposed glyphs.) Using a missing character generates a warning message, as does specifying an unimplemented encoding.  File: texinfo, Node: Defining New Texinfo Commands, Next: Hardcopy, Prev: Internationalization, Up: Top 19 Defining New Texinfo Commands ******************************** Texinfo provides several ways to define new commands: * A Texinfo "macro" allows you to define a new Texinfo command as any sequence of text and/or existing commands (including other macros). The macro can have any number of "parameters"--text you supply each time you use the macro. Incidentally, these macros have nothing to do with the `@defmac' command, which is for documenting macros in the subject of the manual (*note Def Cmd Template::). * `@alias' is a convenient way to define a new name for an existing command. * `@definfoenclose' allows you to define new commands with customized output in the Info file. * Menu: * Defining Macros:: Defining and undefining new commands. * Invoking Macros:: Using a macro, once you've defined it. * Macro Details:: Limitations of Texinfo macros. * alias:: Command aliases. * definfoenclose:: Customized highlighting.  File: texinfo, Node: Defining Macros, Next: Invoking Macros, Up: Defining New Texinfo Commands 19.1 Defining Macros ==================== You use the Texinfo `@macro' command to define a macro, like this: @macro MACRONAME{PARAM1, PARAM2, ...} TEXT ... \PARAM1\ ... @end macro The "parameters" PARAM1, PARAM2, ... correspond to arguments supplied when the macro is subsequently used in the document (described in the next section). For a macro to work consistently with TeX, MACRONAME must consist entirely of letters: no digits, hyphens, underscores, or other special characters. So, we recommend using only letters. However, `makeinfo' will accept anything except `{}_^='; `_' and `^' are excluded so that macros can be called in `@math' mode without a following space (*note `@math': math.). If a macro needs no parameters, you can define it either with an empty list (`@macro foo {}') or with no braces at all (`@macro foo'). The definition or "body" of the macro can contain most Texinfo commands, including previously-defined macros. Not-yet-defined macro invocations are not allowed; thus, it is not possible to have mutually recursive Texinfo macros. Also, a macro definition that defines another macro does not work in TeX due to limitations in the design of `@macro'. In the macro body, instances of a parameter name surrounded by backslashes, as in `\PARAM1\' in the example above, are replaced by the corresponding argument from the macro invocation. You can use parameter names any number of times in the body, including zero. To get a single `\' in the macro expansion, use `\\'. Any other use of `\' in the body yields a warning. The newlines after the `@macro' line and before the `@end macro' line are ignored, that is, not included in the macro body. All other whitespace is treated according to the usual Texinfo rules. To allow a macro to be used recursively, that is, in an argument to a call to itself, you must define it with `@rmacro', like this: @rmacro rmac {arg} a\arg\b @end rmacro ... @rmac{1@rmac{text}2} This produces the output `a1atextb2b'. With `@macro' instead of `@rmacro', an error message is given. You can undefine a macro FOO with `@unmacro FOO'. It is not an error to undefine a macro that is already undefined. For example: @unmacro foo  File: texinfo, Node: Invoking Macros, Next: Macro Details, Prev: Defining Macros, Up: Defining New Texinfo Commands 19.2 Invoking Macros ==================== After a macro is defined (see the previous section), you can use ("invoke") it in your document like this: @MACRONAME {ARG1, ARG2, ...} and the result will be just as if you typed the body of MACRONAME at that spot. For example: @macro foo {p, q} Together: \p\ & \q\. @end macro @foo{a, b} produces: Together: a & b. Thus, the arguments and parameters are separated by commas and delimited by braces; any whitespace after (but not before) a comma is ignored. The braces are required in the invocation (but not the definition), even when the macro takes no arguments, consistent with all other Texinfo commands. For example: @macro argless {} No arguments here. @end macro @argless{} produces: No arguments here. Passing strings containing commas as macro arguments requires special care, since they should be properly "quoted" to prevent `makeinfo' from confusing them with argument separators. To manually quote a comma, prepend it with a backslash character, like this: `\,'. Alternatively, use the `@comma' command (*note Inserting a Comma::). However, to facilitate use of macros, `makeinfo' implements a set of rules called "automatic quoting": 1. If a macro takes only one argument, all commas in its invocation are quoted by default. For example: @macro FIXME{text} @strong{FIXME: \text\} @end macro @FIXME{A nice feature, though it can be dangerous.} will produce the following output *FIXME: A nice feature, though it can be dangerous.* And indeed, it can. Namely, `makeinfo' does not control number of arguments passed to one-argument macros, so be careful when you invoke them. 2. If a macro invocation includes another command (including a recursive invocation of itself), any commas in the nested command invocation(s) are quoted by default. For example, in @say{@strong{Yes, I do}, person one} the comma after `Yes' is implicitly quoted. Here's another example, with a recursive macro: @rmacro cat{a,b} \a\\b\ @end rmacro @cat{@cat{foo, bar}, baz} will produce the string `foobarbaz'. 3. Otherwise, a comma should be explicitly quoted, as above, to be treated as a part of an argument. Other characters that need to be quoted in macro arguments are curly braces and backslash. For example @MACNAME {\\\{\}\,} will pass the (almost certainly error-producing) argument `\{},' to MACNAME. However, commas in parameters, even if escaped by a backslash, might cause trouble in TeX. If the macro is defined to take a single argument, and is invoked without any braces, the entire rest of the line after the macro name is supplied as the argument. For example: @macro bar {p} Twice: \p\ & \p\. @end macro @bar aah produces: Twice: aah & aah. If the macro is defined to take a single argument, and is invoked with braces, the braced text is passed as the argument, regardless of commas. For example: @macro bar {p} Twice: \p\ & \p\. @end macro @bar{a,b} produces: Twice: a,b & a,b.  File: texinfo, Node: Macro Details, Next: alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands 19.3 Macro Details and Caveats ============================== Due to unavoidable limitations, certain macro-related constructs cause problems with TeX. If you get macro-related errors when producing the printed version of a manual, try expanding the macros with `makeinfo' by invoking `texi2dvi' with the `-E' option (*note Format with texi2dvi::). * As mentioned earlier, macro names must consist entirely of letters. * It is not advisable to redefine any TeX primitive, plain, or Texinfo command name as a macro. Unfortunately this is a very large set of names, and the possible resulting errors are unpredictable. * All macros are expanded inside at least one TeX group. This means that `@set' and other such commands have no effect inside a macro. * Commas in macro arguments, even if escaped by a backslash, don't always work. * Macro arguments cannot cross lines. * It is (usually) best to avoid comments inside macro definitions, but see the next item. * Macros containing a command which must be on a line by itself, such as a conditional, cannot be invoked in the middle of a line. In general, the interaction of newlines in the macro definitions and invocations depends on the precise commands and context. You may be able to work around some problems with judicious use of `@c'. Suppose you define a macro that is always intended to be used on a line by itself: @macro linemac @cindex whatever @c @end macro ... foo @linemac bar Without the `@c', there will be an unwanted blank line between the `@cindex whatever' and the `bar' (one newline comes from the macro definition, one from after the invocation), causing a paragraph break. On the other hand, you wouldn't want the `@c' if the macro was sometimes invoked in the middle of a line (the text after the invocation would be treated as a comment). * In general, you can't arbitrarily substitute a macro call for Texinfo command arguments, even when the text is the same. It might work with some commands, it fails with others. Best not to do it at all. For instance, this fails: @macro offmacro off @end macro @headings @offmacro You would expect this to be equivalent to `@headings off', but for TeXnical reasons, it fails with a mysterious error message (`Paragraph ended before @headings was complete'). * Macros cannot define macros in the natural way. To do this, you must use conditionals and raw TeX. For example: @ifnottex @macro ctor {name, arg} @macro \name\ something involving \arg\ somehow @end macro @end macro @end ifnottex @tex \gdef\ctor#1{\ctorx#1,} \gdef\ctorx#1,#2,{\def#1{something involving #2 somehow}} @end tex The `makeinfo' implementation also has limitations: * `@verbatim' and macros do not mix; for instance, you can't start a verbatim block inside a macro and end it outside. (*Note verbatim::.) Starting any environment inside a macro and ending it outside may or may not work, for that matter. * Macros that completely define macros are ok, but it's not possible to have incorrectly nested macro definitions. That is, `@macro' and `@end macro' (likewise for `@rmacro') must be correctly paired. For example, you cannot start a macro definition within a macro, and then end the nested definition outside the macro. * `@rmacro' is a kludge. One more limitation is common to both implementations: white space is ignored at the beginnings of lines. Future major revisions of Texinfo may ease some of these limitations (by introducing a new macro syntax).  File: texinfo, Node: alias, Next: definfoenclose, Prev: Macro Details, Up: Defining New Texinfo Commands 19.4 `@alias NEW=EXISTING' ========================== The `@alias' command defines a new command to be just like an existing one. This is useful for defining additional markup names, thus preserving semantic information in the input even though the output result may be the same. Write the `@alias' command on a line by itself, followed by the new command name, an equals sign, and the existing command name. Whitespace around the equals sign is ignored. Thus: @alias NEW = EXISTING For example, if your document contains citations for both books and some other media (movies, for example), you might like to define a macro `@moviecite{}' that does the same thing as an ordinary `@cite{}' but conveys the extra semantic information as well. You'd do this as follows: @alias moviecite = cite Macros do not always have the same effect as aliases, due to vagaries of argument parsing. Also, aliases are much simpler to define than macros. So the command is not redundant. (It was also heavily used in the Jargon File!) Aliases must not be recursive, directly or indirectly. It is not advisable to redefine any TeX primitive, plain, or Texinfo command name as an alias. Unfortunately this is a very large set of names, and the possible resulting errors are completely random.  File: texinfo, Node: definfoenclose, Prev: alias, Up: Defining New Texinfo Commands 19.5 `definfoenclose': Customized Highlighting ============================================== A `@definfoenclose' command may be used to define a highlighting command for Info, but not for TeX. A command defined using `@definfoenclose' marks text by enclosing it in strings that precede and follow the text. You can use this to get closer control of your Info output. Presumably, if you define a command with `@definfoenclose' for Info, you will create a corresponding command for TeX, either in `texinfo.tex', `texinfo.cnf', or within an `@iftex' in your document. Write a `@definfoenclose' command on a line and follow it with three arguments separated by commas. The first argument to `@definfoenclose' is the @-command name (without the `@'); the second argument is the Info start delimiter string; and the third argument is the Info end delimiter string. The latter two arguments enclose the highlighted text in the Info file. A delimiter string may contain spaces. Neither the start nor end delimiter is required. If you do not want a start delimiter but do want an end delimiter, you must follow the command name with two commas in a row; otherwise, the Info formatting commands will naturally misinterpret the end delimiter string you intended as the start delimiter string. If you do a `@definfoenclose' on the name of a predefined macro (such as `@emph', `@strong', `@t', or `@i'), the enclosure definition will override the built-in definition. An enclosure command defined this way takes one argument in braces; this is intended for new markup commands (*note Marking Text::). For example, you can write: @definfoenclose phoo,//,\\ near the beginning of a Texinfo file to define `@phoo' as an Info formatting command that inserts `//' before and `\\' after the argument to `@phoo'. You can then write `@phoo{bar}' wherever you want `//bar\\' highlighted in Info. Also, for TeX formatting, you could write @iftex @global@let@phoo=@i @end iftex to define `@phoo' as a command that causes TeX to typeset the argument to `@phoo' in italics. Each definition applies to its own formatter: one for TeX, the other for `texinfo-format-buffer' or `texinfo-format-region'. The `@definfoenclose' command need not be within `@ifinfo', but the raw TeX commands do need to be in `@iftex'. Here is another example: write @definfoenclose headword, , : near the beginning of the file, to define `@headword' as an Info formatting command that inserts nothing before and a colon after the argument to `@headword'. `@definfoenclose' definitions must not be recursive, directly or indirectly.  File: texinfo, Node: Hardcopy, Next: Creating and Installing Info Files, Prev: Defining New Texinfo Commands, Up: Top 20 Formatting and Printing Hardcopy *********************************** There are three major shell commands for making a printed manual from a Texinfo file: one for converting the Texinfo file into a file that will be printed, a second for sorting indices, and a third for printing the formatted document. When you use the shell commands, you can either work directly in the operating system shell or work within a shell inside GNU Emacs. If you are using GNU Emacs, you can use commands provided by Texinfo mode instead of shell commands. In addition to the three commands to format a file, sort the indices, and print the result, Texinfo mode offers key bindings for commands to recenter the output buffer, show the print queue, and delete a job from the print queue. * Menu: * Use TeX:: Use TeX to format for hardcopy. * Format with tex/texindex:: How to format with explicit shell commands. * Format with texi2dvi:: A simpler way to format. * Print with lpr:: How to print. * Within Emacs:: How to format and print from an Emacs shell. * Texinfo Mode Printing:: How to format and print in Texinfo mode. * Compile-Command:: How to print using Emacs's compile command. * Requirements Summary:: TeX formatting requirements summary. * Preparing for TeX:: What to do before you use TeX. * Overfull hboxes:: What are and what to do with overfull hboxes. * smallbook:: How to print small format books and manuals. * A4 Paper:: How to print on A4 or A5 paper. * pagesizes:: How to print with customized page sizes. * Cropmarks and Magnification:: How to print marks to indicate the size of pages and how to print scaled up output. * PDF Output:: Portable Document Format output. * Obtaining TeX:: How to Obtain TeX.  File: texinfo, Node: Use TeX, Next: Format with tex/texindex, Up: Hardcopy 20.1 Use TeX ============ The typesetting program called TeX is used for formatting a Texinfo file. TeX is a very powerful typesetting program and, if used correctly, does an exceptionally good job. (*Note How to Obtain TeX: Obtaining TeX, for information on how to obtain TeX.) The standalone `makeinfo' program and Emacs functions `texinfo-format-region' and `texinfo-format-buffer' commands read the very same @-commands in the Texinfo file as does TeX, but process them differently to make an Info file (*note Creating an Info File::).  File: texinfo, Node: Format with tex/texindex, Next: Format with texi2dvi, Prev: Use TeX, Up: Hardcopy 20.2 Format with `tex' and `texindex' ===================================== You can format the Texinfo file with the shell command `tex' followed by the name of the Texinfo file. For example: tex foo.texi TeX will produce a "DVI file" as well as several auxiliary files containing information for indices, cross references, etc. The DVI file (for "DeVice Independent" file) can be printed on virtually any device (see the following sections). The `tex' formatting command itself does not sort the indices; it writes an output file of unsorted index data. To generate a printed index after running the `tex' command, you first need a sorted index to work from. The `texindex' command sorts indices. (The source file `texindex.c' comes as part of the standard Texinfo distribution, among other places.) (`texi2dvi' runs `tex' and `texindex' as necessary.) The `tex' formatting command outputs unsorted index files under names that obey a standard convention: the name of your main input file with any `.tex' (or similar, *note tex invocation: (web2c)tex invocation.) extension removed, followed by the two letter names of indices. For example, the raw index output files for the input file `foo.texinfo' would be `foo.cp', `foo.vr', `foo.fn', `foo.tp', `foo.pg' and `foo.ky'. Those are exactly the arguments to give to `texindex'. Instead of specifying all the unsorted index file names explicitly, you can use `??' as shell wildcards and give the command in this form: texindex foo.?? This command will run `texindex' on all the unsorted index files, including any that you have defined yourself using `@defindex' or `@defcodeindex'. (You may execute `texindex foo.??' even if there are similarly named files with two letter extensions that are not index files, such as `foo.el'. The `texindex' command reports but otherwise ignores such files.) For each file specified, `texindex' generates a sorted index file whose name is made by appending `s' to the input file name. The `@printindex' command looks for a file with that name (*note Printing Indices & Menus::). `texindex' does not alter the raw index output file. After you have sorted the indices, you need to rerun `tex' on the Texinfo file. This regenerates the DVI file, this time with up-to-date index entries. Finally, you may need to run `tex' one more time, to get the page numbers in the cross-references correct. To summarize, this is a five step process: 1. Run `tex' on your Texinfo file. This generates a DVI file (with undefined cross-references and no indices), and the raw index files (with two letter extensions). 2. Run `texindex' on the raw index files. This creates the corresponding sorted index files (with three letter extensions). 3. Run `tex' again on your Texinfo file. This regenerates the DVI file, this time with indices and defined cross-references, but with page numbers for the cross-references from last time, generally incorrect. 4. Sort the indices again, with `texindex'. 5. Run `tex' one last time. This time the correct page numbers are written for the cross-references. Alternatively, it's a one-step process: run `texi2dvi' (*note Format with texi2dvi::). You need not run `texindex' each time after you run `tex'. If you do not, on the next run, the `tex' formatting command will use whatever sorted index files happen to exist from the previous use of `texindex'. This is usually ok while you are debugging. Sometimes you may wish to print a document while you know it is incomplete, or to print just one chapter of a document. In that case, the usual auxiliary files that TeX creates and warnings TeX gives when cross-references are not satisfied are just nuisances. You can avoid them with the `@novalidate' command, which you must give _before_ the `@setfilename' command (*note `@setfilename': setfilename.). Thus, the beginning of your file would look approximately like this: \input texinfo @novalidate @setfilename myfile.info ... `@novalidate' also turns off validation in `makeinfo', just like its `--no-validate' option (*note Pointer Validation::).  File: texinfo, Node: Format with texi2dvi, Next: Print with lpr, Prev: Format with tex/texindex, Up: Hardcopy 20.3 Format with `texi2dvi' =========================== The `texi2dvi' command automatically runs both TeX and `texindex' as many times as necessary to produce a DVI file with sorted indices and all cross-references resolved. It is therefore simpler than manually executing the `tex'--`texindex'--`tex'--`tex' sequence described in the previous section. To run `texi2dvi' on an input file `foo.texi', do this (where `prompt$ ' is your shell prompt): prompt$ texi2dvi foo.texi As shown in this example, the input filenames to `texi2dvi' must include any extension (`.texi', `.texinfo', etc.). Under MS-DOS and perhaps in other circumstances, you may need to run `sh texi2dvi foo.texi' instead of relying on the operating system to invoke the shell on the `texi2dvi' script. One useful option to `texi2dvi' is `--command=CMD'. This inserts CMD on a line by itself after the `@setfilename' in a temporary copy of the input file before running TeX. With this, you can specify different printing formats, such as `@smallbook' (*note smallbook::), `@afourpaper' (*note A4 Paper::), or `@pagesizes' (*note pagesizes::), without actually changing the document source. (You can also do this on a site-wide basis with `texinfo.cnf'; *note Preparing for TeX: Preparing for TeX.). With the `--pdf' option, `texi2dvi' produces PDF output instead of DVI (*note PDF Output::), by running `pdftex' instead of `tex'. Alternatively, the command `texi2pdf' is an abbreviation for running `texi2dvi --pdf'. The command `pdftexi2dvi' is also supported as a convenience to AUC-TeX users, since the latter merely prepends `pdf' to DVI producing tools to have PDF producing tools. `texi2dvi' can also be used to process LaTeX files; simply run `texi2dvi filename.ext'. Normally `texi2dvi' is able to guess the input file language by its contents and file name suffix. If, however, it fails to do so you can specify the input language using `--language=LANG' command line option, where LANG is either `latex' or `texinfo'. `texi2dvi' will use `etex' (or `pdfetex') if they are available; these extended versions of TeX are not required, and the DVI (or PDF) output is identical, but they simplify the TeX programming in some cases, and provide additional tracing information when debugging `texinfo.tex'. Several options are provided for handling documents, written in character sets other than ASCII. The `--translate-file=FILE' option instructs `texi2dvi' to translate input into internal TeX character set using "translation file" FILE (*note TCX files: (web2c)TCX files.). The options `--recode' and `--recode-from=ENC' allow conversion of an input document before running TeX. The `--recode' option recodes the document from encoding specified by `@documentencoding' command (*note `documentencoding': documentencoding.) to plain 7-bit `texinfo' encoding. The option `--recode-from=ENC' recodes the document from ENC encoding to the encoding specified by `@documentencoding'. This is useful, for example, if the document is written in `UTF-8' encoding and an equivalent 8-bit encoding is supported by `makeinfo'. Both `--recode' and `--recode-from=ENC' use `recode' utility to perform the conversion. If `recode' fails to process the file, `texi2dvi' prints a warning and continues using unmodified input file. For a list of other options, run `texi2dvi --help'.  File: texinfo, Node: Print with lpr, Next: Within Emacs, Prev: Format with texi2dvi, Up: Hardcopy 20.4 Shell Print Using `lpr -d' =============================== The precise command to print a DVI file depends on your system installation. Two common ones are `dvips foo.dvi -o' and `lpr -d foo.dvi'. For example, the following commands will (perhaps) suffice to sort the indices, format, and print the `Bison Manual': tex bison.texinfo texindex bison.?? tex bison.texinfo lpr -d bison.dvi (Remember that the shell commands may be different at your site; but these are commonly used versions.) Using the `texi2dvi' shell script (see the previous section): texi2dvi bison.texinfo lpr -d bison.dvi # or perhaps dvips bison.dvi -o `lpr' is a standard program on Unix systems, but it is usually absent on MS-DOS/MS-Windows. Some network packages come with a program named `lpr', but these are usually limited to sending files to a print server over the network, and generally don't support the `-d' option. If you are unfortunate enough to work on one of these systems, you have several alternative ways of printing DVI files: * Find and install a Unix-like `lpr' program, or its clone. If you can do that, you will be able to print DVI files just like described above. * Send the DVI files to a network printer queue for DVI files. Some network printers have special queues for printing DVI files. You should be able to set up your network software to send files to that queue. In some cases, the version of `lpr' which comes with your network software will have a special option to send a file to specific queues, like this: lpr -Qdvi -hprint.server.domain bison.dvi * Convert the DVI file to a Postscript or PCL file and send it to your local printer. *Note Invoking Dvips: (dvips)Invoking Dvips, and the man pages for `dvilj', for detailed description of these tools. Once the DVI file is converted to the format your local printer understands directly, just send it to the appropriate port, usually `PRN'.  File: texinfo, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Hardcopy 20.5 From an Emacs Shell ======================== You can give formatting and printing commands from a shell within GNU Emacs. To create a shell within Emacs, type `M-x shell'. In this shell, you can format and print the document. *Note Format and Print Hardcopy: Hardcopy, for details. You can switch to and from the shell buffer while `tex' is running and do other editing. If you are formatting a long document on a slow machine, this can be very convenient. You can also use `texi2dvi' from an Emacs shell. For example, here is how to use `texi2dvi' to format and print `Using and Porting GNU CC' from a shell within Emacs: texi2dvi gcc.texinfo lpr -d gcc.dvi See the next section for more information about formatting and printing in Texinfo mode.  File: texinfo, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Hardcopy 20.6 Formatting and Printing in Texinfo Mode ============================================ Texinfo mode provides several predefined key commands for TeX formatting and printing. These include commands for sorting indices, looking at the printer queue, killing the formatting job, and recentering the display of the buffer in which the operations occur. `C-c C-t C-b' `M-x texinfo-tex-buffer' Run `texi2dvi' on the current buffer. `C-c C-t C-r' `M-x texinfo-tex-region' Run TeX on the current region. `C-c C-t C-i' `M-x texinfo-texindex' Sort the indices of a Texinfo file formatted with `texinfo-tex-region'. `C-c C-t C-p' `M-x texinfo-tex-print' Print a DVI file that was made with `texinfo-tex-region' or `texinfo-tex-buffer'. `C-c C-t C-q' `M-x tex-show-print-queue' Show the print queue. `C-c C-t C-d' `M-x texinfo-delete-from-print-queue' Delete a job from the print queue; you will be prompted for the job number shown by a preceding `C-c C-t C-q' command (`texinfo-show-tex-print-queue'). `C-c C-t C-k' `M-x tex-kill-job' Kill the currently running TeX job started by either `texinfo-tex-region' or `texinfo-tex-buffer', or any other process running in the Texinfo shell buffer. `C-c C-t C-x' `M-x texinfo-quit-job' Quit a TeX formatting job that has stopped because of an error by sending an to it. When you do this, TeX preserves a record of what it did in a `.log' file. `C-c C-t C-l' `M-x tex-recenter-output-buffer' Redisplay the shell buffer in which the TeX printing and formatting commands are run to show its most recent output. Thus, the usual sequence of commands for formatting a buffer is as follows (with comments to the right): C-c C-t C-b Run `texi2dvi' on the buffer. C-c C-t C-p Print the DVI file. C-c C-t C-q Display the printer queue. The Texinfo mode TeX formatting commands start a subshell in Emacs called the `*tex-shell*'. The `texinfo-tex-command', `texinfo-texindex-command', and `tex-dvi-print-command' commands are all run in this shell. You can watch the commands operate in the `*tex-shell*' buffer, and you can switch to and from and use the `*tex-shell*' buffer as you would any other shell buffer. The formatting and print commands depend on the values of several variables. The default values are: Variable Default value texinfo-texi2dvi-command "texi2dvi" texinfo-tex-command "tex" texinfo-texindex-command "texindex" texinfo-delete-from-print-queue-command "lprm" texinfo-tex-trailer "@bye" tex-start-of-header "%**start" tex-end-of-header "%**end" tex-dvi-print-command "lpr -d" tex-show-queue-command "lpq" You can change the values of these variables with the `M-x set-variable' command (*note Examining and Setting Variables: (emacs)Examining.), or with your `.emacs' initialization file (*note Init File: (emacs)Init File.). Beginning with version 20, GNU Emacs offers a user-friendly interface, called "Customize", for changing values of user-definable variables. *Note Easy Customization Interface: (emacs)Easy Customization, for more details about this. The Texinfo variables can be found in the `Development/Docs/Texinfo' group, once you invoke the `M-x customize' command.  File: texinfo, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Hardcopy 20.7 Using the Local Variables List =================================== Yet another way to apply the TeX formatting command to a Texinfo file is to put that command in a "local variables list" at the end of the Texinfo file. You can then specify the `tex' or `texi2dvi' commands as a `compile-command' and have Emacs run it by typing `M-x compile'. This creates a special shell called the `*compilation*' buffer in which Emacs runs the compile command. For example, at the end of the `gdb.texinfo' file, after the `@bye', you could put the following: Local Variables: compile-command: "texi2dvi gdb.texinfo" End: This technique is most often used by programmers who also compile programs this way; see *note Compilation: (emacs)Compilation.  File: texinfo, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Hardcopy 20.8 TeX Formatting Requirements Summary ======================================== Every Texinfo file that is to be input to TeX must begin with a `\input' command and must contain an `@setfilename' command: \input texinfo @setfilename ARG-NOT-USED-BY-TEX The first command instructs TeX to load the macros it needs to process a Texinfo file and the second command opens auxiliary files. Every Texinfo file must end with a line that terminates TeX's processing and forces out unfinished pages: @bye Strictly speaking, these lines are all a Texinfo file needs to be processed successfully by TeX. Usually, however, the beginning includes an `@settitle' command to define the title of the printed manual, an `@setchapternewpage' command, a title page, a copyright page, and permissions. Besides an `@bye', the end of a file usually includes indices and a table of contents. (And of course most manuals contain a body of text as well.) For more information, see: * *note `@settitle': settitle. * *note `@setchapternewpage': setchapternewpage. * *note Page Headings: Headings. * *note Titlepage & Copyright Page::. * *note Printing Indices & Menus::. * *note Contents::.  File: texinfo, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Hardcopy 20.9 Preparing for TeX ====================== TeX needs to know where to find the `texinfo.tex' file that the `\input texinfo' command on the first line reads. The `texinfo.tex' file tells TeX how to handle @-commands; it is included in all standard GNU distributions. The latest version is always available from the Texinfo source repository: `http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD' Usually, the installer has put the `texinfo.tex' file in the default directory that contains TeX macros when GNU Texinfo, Emacs or other GNU software is installed. In this case, TeX will find the file and you do not need to do anything special. If this has not been done, you can put `texinfo.tex' in the current directory when you run TeX, and TeX will find it there. Also, you should install `epsf.tex', if it is not already installed from another distribution. More details are at the end of the description of the `@image' command (*note Images::). To be able to use quotation marks other than those used in English you'll need to install European Computer Modern fonts and optionally CM-Super fonts, unless they are already installed (*note Inserting Quotation Marks::). If you intend to use the `@euro' command, you should install the Euro font, if it is not already installed. *Note euro::. Optionally, you may create an additional `texinfo.cnf', and install it as well. This file is read by TeX when the `@setfilename' command is executed (*note `@setfilename': setfilename.). You can put any commands you like there, according to local site-wide conventions. They will be read by TeX when processing any Texinfo document. For example, if `texinfo.cnf' contains the line `@afourpaper' (*note A4 Paper::), then all Texinfo documents will be processed with that page size in effect. If you have nothing to put in `texinfo.cnf', you do not need to create it. If neither of the above locations for these system files suffice for you, you can specify the directories explicitly. For `texinfo.tex', you can do this by writing the complete path for the file after the `\input' command. Another way, that works for both `texinfo.tex' and `texinfo.cnf' (and any other file TeX might read), is to set the `TEXINPUTS' environment variable in your `.cshrc' or `.profile' file. Which you use of `.cshrc' or `.profile' depends on whether you use a Bourne shell-compatible (`sh', `bash', `ksh', ...) or C shell-compatible (`csh', `tcsh') command interpreter. The latter read the `.cshrc' file for initialization information, and the former read `.profile'. In a `.cshrc' file, you could use the following `csh' command sequence: setenv TEXINPUTS .:/home/me/mylib: In a `.profile' file, you could use the following `sh' command sequence: TEXINPUTS=.:/home/me/mylib: export TEXINPUTS On MS-DOS/MS-Windows, you would say it like this(1): set TEXINPUTS=.;d:/home/me/mylib;c: It is customary for DOS/Windows users to put such commands in the `autoexec.bat' file, or in the Windows Registry. These settings would cause TeX to look for `\input' file first in the current directory, indicated by the `.', then in a hypothetical user `me''s `mylib' directory, and finally in the system directories. (A leading, trailing, or doubled `:' indicates searching the system directories at that point.) Finally, you may wish to dump a `.fmt' file (*note Memory dumps: (web2c)Memory dumps.) so that TeX can load Texinfo faster. (The disadvantage is that then updating `texinfo.tex' requires redumping.) You can do this by running this command, assuming `epsf.tex' is findable by TeX: initex texinfo @dump (`dump' is a TeX primitive.) Then, move `texinfo.fmt' to wherever your `.fmt' files are found; typically, this will be in the subdirectory `web2c' of your TeX installation. ---------- Footnotes ---------- (1) Note the use of the `;' character, instead of `:', as directory separator on these systems.  File: texinfo, Node: Overfull hboxes, Next: smallbook, Prev: Preparing for TeX, Up: Hardcopy 20.10 Overfull "hboxes" ======================= TeX is sometimes unable to typeset a line without extending it into the right margin. This can occur when TeX comes upon what it interprets as a long word that it cannot hyphenate, such as an electronic mail network address or a very long title. When this happens, TeX prints an error message like this: Overfull @hbox (20.76302pt too wide) (In TeX, lines are in "horizontal boxes", hence the term, "hbox". `@hbox' is a TeX primitive not needed in the Texinfo language.) TeX also provides the line number in the Texinfo source file and the text of the offending line, which is marked at all the places that TeX considered hyphenation. *Note Catching Errors with TeX Formatting: Debugging with TeX, for more information about typesetting errors. If the Texinfo file has an overfull hbox, you can rewrite the sentence so the overfull hbox does not occur, or you can decide to leave it. A small excursion into the right margin often does not matter and may not even be noticeable. If you have many overfull boxes and/or an antipathy to rewriting, you can coerce TeX into greatly increasing the allowable interword spacing, thus (if you're lucky) avoiding many of the bad line breaks, like this: @tex \global\emergencystretch = .9\hsize @end tex (You should adjust the fraction as needed.) This huge value for `\emergencystretch' cannot be the default, since then the typeset output would generally be of noticeably lower quality; the default is `.15\hsize'. `\hsize' is the TeX dimension containing the current line width. For what overfull boxes you have, however, TeX will print a large, ugly, black rectangle beside the line that contains the overfull hbox unless told otherwise. This is so you will notice the location of the problem if you are correcting a draft. To prevent such a monstrosity from marring your final printout, write the following in the beginning of the Texinfo file on a line of its own, before the `@titlepage' command: @finalout  File: texinfo, Node: smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Hardcopy 20.11 Printing "Small" Books ============================ By default, TeX typesets pages for printing in an 8.5 by 11 inch format. However, you can direct TeX to typeset a document in a 7 by 9.25 inch format that is suitable for bound books by inserting the following command on a line by itself at the beginning of the Texinfo file, before the title page: @smallbook (Since many books are about 7 by 9.25 inches, this command might better have been called the `@regularbooksize' command, but it came to be called the `@smallbook' command by comparison to the 8.5 by 11 inch format.) If you write the `@smallbook' command between the start-of-header and end-of-header lines, the Texinfo mode TeX region formatting command, `texinfo-tex-region', will format the region in "small" book size (*note Start of Header::). *Note small::, for information about commands that make it easier to produce examples for a smaller manual. *Note Format with texi2dvi::, and *note Preparing for TeX: Preparing for TeX, for other ways to format with `@smallbook' that do not require changing the source file.  File: texinfo, Node: A4 Paper, Next: pagesizes, Prev: smallbook, Up: Hardcopy 20.12 Printing on A4 Paper ========================== You can tell TeX to format a document for printing on European size A4 paper (or A5) with the `@afourpaper' (or `@afivepaper') command. Write the command on a line by itself near the beginning of the Texinfo file, before the title page. For example, this is how you would write the header for this manual: \input texinfo @c -*-texinfo-*- @c %**start of header @setfilename texinfo @settitle Texinfo @afourpaper @c %**end of header *Note Format with texi2dvi::, and *note Preparing for TeX: Preparing for TeX, for other ways to format for different paper sizes that do not require changing the source file. You may or may not prefer the formatting that results from the command `@afourlatex'. There's also `@afourwide' for A4 paper in wide format.  File: texinfo, Node: pagesizes, Next: Cropmarks and Magnification, Prev: A4 Paper, Up: Hardcopy 20.13 `@pagesizes' [WIDTH][, HEIGHT]: Custom Page Sizes ======================================================= You can explicitly specify the height and (optionally) width of the main text area on the page with the `@pagesizes' command. Write this on a line by itself near the beginning of the Texinfo file, before the title page. The height comes first, then the width if desired, separated by a comma. Examples: @pagesizes 200mm,150mm and @pagesizes 11.5in This would be reasonable for printing on B5-size paper. To emphasize, this command specifies the size of the _text area_, not the size of the paper (which is 250mm by 177mm for B5, 14in by 8.5in for legal). To make more elaborate changes, such as changing any of the page margins, you must define a new command in `texinfo.tex' (or `texinfo.cnf', *note Preparing for TeX: Preparing for TeX.). *Note Format with texi2dvi::, and *note Preparing for TeX: Preparing for TeX, for other ways to specify `@pagesizes' that do not require changing the source file. `@pagesizes' is ignored by `makeinfo'.  File: texinfo, Node: Cropmarks and Magnification, Next: PDF Output, Prev: pagesizes, Up: Hardcopy 20.14 Cropmarks and Magnification ================================= You can (attempt to) direct TeX to print cropmarks at the corners of pages with the `@cropmarks' command. Write the `@cropmarks' command on a line by itself between `@iftex' and `@end iftex' lines near the beginning of the Texinfo file, before the title page, like this: @iftex @cropmarks @end iftex This command is mainly for printers that typeset several pages on one sheet of film; but you can attempt to use it to mark the corners of a book set to 7 by 9.25 inches with the `@smallbook' command. (Printers will not produce cropmarks for regular sized output that is printed on regular sized paper.) Since different printing machines work in different ways, you should explore the use of this command with a spirit of adventure. You may have to redefine the command in `texinfo.tex'. You can attempt to direct TeX to typeset pages larger or smaller than usual with the `\mag' TeX command. Everything that is typeset is scaled proportionally larger or smaller. (`\mag' stands for "magnification".) This is _not_ a Texinfo @-command, but is a plain TeX command that is prefixed with a backslash. You have to write this command between `@tex' and `@end tex' (*note Raw Formatter Commands::). Follow the `\mag' command with an `=' and then a number that is 1000 times the magnification you desire. For example, to print pages at 1.2 normal size, write the following near the beginning of the Texinfo file, before the title page: @tex \mag=1200 @end tex With some printing technologies, you can print normal-sized copies that look better than usual by giving a larger-than-normal master to your print shop. They do the reduction, thus effectively increasing the resolution. Depending on your system, DVI files prepared with a nonstandard-`\mag' may not print or may print only with certain magnifications. Be prepared to experiment.  File: texinfo, Node: PDF Output, Next: Obtaining TeX, Prev: Cropmarks and Magnification, Up: Hardcopy 20.15 PDF Output ================ The simplest way to generate PDF output from Texinfo source is to run the convenience script `texi2pdf' (or `pdftexi2dvi'); this simply executes the `texi2dvi' script with the `--pdf' option (*note Format with texi2dvi::). If for some reason you want to process the document by hand, simply run the `pdftex' program instead of plain `tex'. That is, run `pdftex foo.texi' instead of `tex foo.texi'. "PDF" stands for `Portable Document Format'. It was invented by Adobe Systems some years ago for document interchange, based on their PostScript language. Related links: * GNU GV, a Ghostscript-based PDF reader (http://www.foolabs.com/xpdf/). (It can also preview PostScript documents.) * A freely available standalone PDF reader (http://www.foolabs.com/xpdf/) for the X window system. * PDF definition (http://partners.adobe.com/asn/acrobat/sdk/public/docs/). At present, Texinfo does not provide `@ifpdf' or `@pdf' commands as for the other output formats, since PDF documents contain many internal links that would be hard or impossible to get right at the Texinfo source level. PDF files require special software to be displayed, unlike the plain ASCII formats (Info, HTML) that Texinfo supports. They also tend to be much larger than the DVI files output by TeX by default. Nevertheless, a PDF file does define an actual typeset document in a self-contained file, so it has its place.  File: texinfo, Node: Obtaining TeX, Prev: PDF Output, Up: Hardcopy 20.16 How to Obtain TeX ======================= TeX is freely redistributable. You can obtain TeX for Unix systems via anonymous ftp or on physical media. The core material consists of the Web2c TeX distribution (`http://tug.org/web2c'). Instructions for retrieval by anonymous ftp and information on other available distributions: `http://tug.org/unixtex.ftp'. The Free Software Foundation provides a core distribution on its Source Code CD-ROM suitable for printing Texinfo manuals. To order it, contact: Free Software Foundation, Inc. 51 Franklin St, Fifth Floor Boston, MA 02110-1301 USA Telephone: +1-617-542-5942 Fax: (including Japan) +1-617-542-2652 Free Dial Fax (in Japan): 0031-13-2473 (KDD) 0066-3382-0158 (IDC) Electronic mail: `gnu@gnu.org' Many other TeX distributions are available; see `http://tug.org/'.  File: texinfo, Node: Creating and Installing Info Files, Next: Generating HTML, Prev: Hardcopy, Up: Top 21 Creating and Installing Info Files ************************************* This chapter describes how to create and install Info files. *Note Info Files::, for general information about the file format itself. * Menu: * Creating an Info File:: * Installing an Info File::  File: texinfo, Node: Creating an Info File, Next: Installing an Info File, Up: Creating and Installing Info Files 21.1 Creating an Info File ========================== `makeinfo' is a program that converts a Texinfo file into an Info file, HTML file, or plain text. `texinfo-format-region' and `texinfo-format-buffer' are GNU Emacs functions that convert Texinfo to Info. For information on installing the Info file in the Info system, *note Installing an Info File::. * Menu: * makeinfo advantages:: `makeinfo' provides better error checking. * Invoking makeinfo:: How to run `makeinfo' from a shell. * makeinfo options:: Specify fill-column and other options. * Pointer Validation:: How to check that pointers point somewhere. * makeinfo in Emacs:: How to run `makeinfo' from Emacs. * texinfo-format commands:: Two Info formatting commands written in Emacs Lisp are an alternative to `makeinfo'. * Batch Formatting:: How to format for Info in Emacs Batch mode. * Tag and Split Files:: How tagged and split files help Info to run better.  File: texinfo, Node: makeinfo advantages, Next: Invoking makeinfo, Up: Creating an Info File 21.1.1 `makeinfo' Preferred --------------------------- The `makeinfo' utility creates an Info file from a Texinfo source file more quickly than either of the Emacs formatting commands and provides better error messages. We recommend it. `makeinfo' is a C program that is independent of Emacs. You do not need to run Emacs to use `makeinfo', which means you can use `makeinfo' on machines that are too small to run Emacs. You can run `makeinfo' in any one of three ways: from an operating system shell, from a shell inside Emacs, or by typing the `C-c C-m C-r' or the `C-c C-m C-b' command in Texinfo mode in Emacs. The `texinfo-format-region' and the `texinfo-format-buffer' commands are useful if you cannot run `makeinfo'. Also, in some circumstances, they format short regions or buffers more quickly than `makeinfo'.  File: texinfo, Node: Invoking makeinfo, Next: makeinfo options, Prev: makeinfo advantages, Up: Creating an Info File 21.1.2 Running `makeinfo' from a Shell -------------------------------------- To create an Info file from a Texinfo file, invoke `makeinfo' followed by the name of the Texinfo file. Thus, to create the Info file for Bison, type the following to the shell: makeinfo bison.texinfo (You can run a shell inside Emacs by typing `M-x shell'.) `makeinfo' has many options to control its actions and output; see the next section. You can give `makeinfo' more than one input file name; each is processed in turn. If an input file name is `-', or no input file names are given at all, standard input is read.  File: texinfo, Node: makeinfo options, Next: Pointer Validation, Prev: Invoking makeinfo, Up: Creating an Info File 21.1.3 Options for `makeinfo' ----------------------------- The `makeinfo' program accepts many options. Perhaps the most commonly needed are those that change the output format. By default, `makeinfo' outputs Info files. Each command line option is a word preceded by `--' or a letter preceded by `-'. You can use abbreviations for the long option names as long as they are unique. For example, you could use the following shell command to create an Info file for `bison.texinfo' in which each line is filled to only 68 columns: makeinfo --fill-column=68 bison.texinfo You can write two or more options in sequence, like this: makeinfo --no-split --fill-column=70 ... This would keep the Info file together as one possibly very long file and would also set the fill column to 70. The options are: `-D VAR' Cause the variable VAR to be defined. This is equivalent to `@set VAR' in the Texinfo file (*note set clear value::). `--commands-in-node-names' Allow `@'-commands in node names. This is not recommended, as it can probably never be implemented in TeX. It also makes `makeinfo' much slower. Also, this option is ignored when `--no-validate' is used. *Note Pointer Validation::, for more details. `--css-include=FILE' Include the contents of FILE, which should contain cascading style sheets specifications, in the `