This is texinfo.info, produced by texi2any version 6.0 from texinfo.texi. This manual is for GNU Texinfo (version 6.0, 26 June 2015), a documentation system that can produce both online information and a printed manual from a single source using semantic markup. Copyright (C) 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997, 1998, 1999, 2001, 2001, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 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.3 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 have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it 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. * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source. * pod2texi: (pod2texi)Invoking pod2texi. Translate Perl POD to Texinfo. * 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. END-INFO-DIR-ENTRY  File: texinfo.info, Node: Two-column Tables, Next: Multi-column Tables, Prev: @enumerate, Up: Lists and Tables 11.4 Making a Two-column Table ============================== '@table' is similar to '@itemize' (*note @itemize::), but allows you to specify a name or heading line for each item. The '@table' command is used to produce two-column tables, and is especially useful for glossaries, explanatory exhibits, and command-line option summaries. * Menu: * @table:: How to construct a two-column table. * @ftable @vtable:: Automatic indexing for two-column tables. * @itemx:: How to put more entries in the first column.  File: texinfo.info, Node: @table, Next: @ftable @vtable, Up: Two-column Tables 11.4.1 Using the '@table' Command --------------------------------- Use the '@table' command to produce two-column tables. It is typically used when you have a list of items and a brief text with each one, such as "definition lists". Write the '@table' command at the beginning of a line, after a blank line, and follow it on the same line with an argument that is a Texinfo "indicating" command such as '@code', '@samp', '@var', '@option', or '@kbd' (*note Indicating::). This command will be applied to the text that goes into the first column of each item and thus determines how it will be highlighted. For example, '@table @code' will cause the text in the first column to be output as if it had been the argument to an '@code' command. You may also use the '@asis' command as an argument to '@table'. '@asis' is a command that does nothing; if you use this command after '@table', the first column entries are output without added highlighting ("as is"). The '@table' command works with other commands besides those explicitly mentioned here. However, you can only use predefined Texinfo commands that normally take an argument in braces. You cannot reliably use a new command defined with '@macro', but an '@alias' (for a suitable predefined command) is acceptable. *Note Defining New Texinfo Commands::. Begin each table entry with an '@item' command at the beginning of a line. Write the first column text on the same line as the '@item' command. Write the second column text on the line following the '@item' line and on subsequent lines. (You do not need to type anything for an empty second column entry.) You may write as many lines of supporting text as you wish, even several paragraphs. But only the text on the same line as the '@item' will be placed in the first column (including any footnotes). Normally, you should put a blank line before an '@item' line (except the first one). This puts a blank line in the Info file. Except when the entries are very brief, a blank line looks better. End the table with a line consisting of '@end table', followed by a blank line. TeX will always start a new paragraph after the table, so the blank line is needed for the Info output to be analogous. The following table, for example, highlights the text in the first column with an '@samp' command: @table @samp @item foo This is the text for @samp{foo}. @item bar Text for @samp{bar}. @end table This produces: 'foo' This is the text for 'foo'. 'bar' Text for 'bar'. If you want to list two or more named items with a single block of text, use the '@itemx' command. (*Note @itemx::.)  File: texinfo.info, Node: @ftable @vtable, Next: @itemx, Prev: @table, Up: Two-column Tables 11.4.2 '@ftable' and '@vtable' ------------------------------ The '@ftable' and '@vtable' commands are the same as the '@table' command except that '@ftable' automatically enters each of the items in the first column of the table into the index of functions and '@vtable' automatically enters each of the items in the first column of the table into the index of variables. This simplifies the task of creating indices. Only the items on the same line as the '@item' commands are indexed, and they are indexed in exactly the form that they appear on that line. *Note Indices::, for more information about indices. Begin a two-column table using '@ftable' or '@vtable' by writing the @-command at the beginning of a line, followed on the same line by an argument that is a Texinfo command such as '@code', exactly as you would for an '@table' command; and end the table with an '@end ftable' or '@end vtable' command on a line by itself. See the example for '@table' in the previous section.  File: texinfo.info, Node: @itemx, Prev: @ftable @vtable, Up: Two-column Tables 11.4.3 '@itemx': Second and Subsequent Items -------------------------------------------- Use the '@itemx' command inside a table when you have two or more first column entries for the same item, each of which should appear on a line of its own. Use '@item' for the first entry, and '@itemx' for all subsequent entries; '@itemx' must always follow an '@item' command, with no blank line intervening. The '@itemx' command works exactly like '@item' except that it does not generate extra vertical space above the first column text. If you have multiple consecutive '@itemx' commands, do not insert any blank lines between them. For example, @table @code @item upcase @itemx downcase These two functions accept a character or a string as argument, and return the corresponding uppercase (lowercase) character or string. @end table This produces: 'upcase' 'downcase' These two functions accept a character or a string as argument, and return the corresponding uppercase (lowercase) character or string. (Note also that this example illustrates multi-line supporting text in a two-column table.)  File: texinfo.info, Node: Multi-column Tables, Prev: Two-column Tables, Up: Lists and Tables 11.5 '@multitable': Multi-column Tables ======================================= '@multitable' allows you to construct tables with any number of columns, with each column having any width you like. You define the column widths on the '@multitable' line itself, and write each row of the actual table following an '@item' command, with columns separated by an '@tab' command. Finally, '@end multitable' completes the table. Details in the sections below. * Menu: * Multitable Column Widths:: Defining multitable column widths. * Multitable Rows:: Defining multitable rows, with examples.  File: texinfo.info, Node: Multitable Column Widths, Next: Multitable Rows, Up: Multi-column Tables 11.5.1 Multitable Column Widths ------------------------------- You can define the column widths for a multitable in two ways: as fractions of the line length; or with a prototype row. Mixing the two methods is not supported. In either case, the widths are defined entirely on the same line as the '@multitable' command. 1. To specify column widths as fractions of the line length, write '@columnfractions' and the decimal numbers (presumably less than 1; a leading zero is allowed and ignored) after the '@multitable' command, as in: @multitable @columnfractions .33 .33 .33 The fractions need not add up exactly to 1.0, as these do not. This allows you to produce tables that do not need the full line length. 2. To specify a prototype row, write the longest entry for each column enclosed in braces after the '@multitable' command. For example: @multitable {some text for column one} {for column two} The first column will then have the width of the typeset 'some text for column one', and the second column the width of 'for column two'. The prototype entries need not appear in the table itself. Although we used simple text in this example, the prototype entries can contain Texinfo commands; markup commands such as '@code' are particularly likely to be useful.  File: texinfo.info, Node: Multitable Rows, Prev: Multitable Column Widths, Up: Multi-column Tables 11.5.2 Multitable Rows ---------------------- After the '@multitable' command defining the column widths (see the previous section), you begin each row in the body of a multitable with '@item', and separate the column entries with '@tab'. Line breaks are not special within the table body, and you may break input lines in your source file as necessary. You can also use '@headitem' instead of '@item' to produce a "heading row". The TeX output for such a row is in bold, and the HTML and Docbook output uses the '' tag. In Info, the heading row is followed by a separator line made of dashes ('-' characters). The command '@headitemfont' can be used in templates when the entries in an '@headitem' row need to be used in a template. It is a synonym for '@b', but using '@headitemfont' avoids any dependency on that particular font style, in case we provide a way to change it in the future. Here is a complete example of a multi-column table (the text is from 'The GNU Emacs Manual', *note Splitting Windows: (emacs)Split Window.): @multitable @columnfractions .15 .45 .4 @headitem Key @tab Command @tab Description @item C-x 2 @tab @code{split-window-vertically} @tab Split the selected window into two windows, with one above the other. @item C-x 3 @tab @code{split-window-horizontally} @tab Split the selected window into two windows positioned side by side. @item C-Mouse-2 @tab @tab In the mode line or scroll bar of a window, split that window. @end multitable produces: Key Command Description --------------------------------------------------------------------------- C-x 2 'split-window-vertically' Split the selected window into two windows, with one above the other. C-x 3 'split-window-horizontally' Split the selected window into two windows positioned side by side. C-Mouse-2 In the mode line or scroll bar of a window, split that window.  File: texinfo.info, Node: Special Displays, Next: Indices, Prev: Lists and Tables, Up: Top 12 Special Displays ******************* The commands in this chapter allow you to write text that is specially displayed (output format permitting), outside of the normal document flow. One set of such commands is for creating "floats", that is, figures, tables, and the like, set off from the main text, possibly numbered, captioned, and/or referred to from elsewhere in the document. Images are often included in these displays. Another group of commands is for creating footnotes in Texinfo. * Menu: * Floats:: Figures, tables, and the like. * Images:: Including graphics and images. * Footnotes:: Writing footnotes.  File: texinfo.info, Node: Floats, Next: Images, Up: Special Displays 12.1 Floats =========== A "float" is a display which is set off from the main text. It is typically labeled as being a "Figure", "Table", "Example", or some similar type. A float is so-named because, in principle, it can be moved to the bottom or top of the current page, or to a following page, in the printed output. (Floating does not make sense in other output formats.) In the present version of Texinfo, however, this floating is unfortunately not yet implemented. Instead, the floating material is simply output at the current location, more or less as if it were an '@group' (*note @group::). * Menu: * @float:: Producing floating material. * @caption @shortcaption:: Specifying descriptions for floats. * @listoffloats:: A table of contents for floats.  File: texinfo.info, Node: @float, Next: @caption @shortcaption, Up: Floats 12.1.1 '@float' [TYPE][,LABEL]: Floating Material ------------------------------------------------- To produce floating material, enclose the material you want to be displayed separate between '@float' and '@end float' commands, on lines by themselves. Floating material often uses '@image' to display an already-existing graphic (*note Images::), or '@multitable' to display a table (*note Multi-column Tables::). However, the contents of the float can be anything. Here's an example with simple text: @float Figure,fig:ex1 This is an example float. @end float And the output: This is an example float. Figure 12.1 As shown in the example, '@float' takes two arguments (separated by a comma), TYPE and LABEL. Both are optional. TYPE Specifies the sort of float this is; typically a word such as "Figure", "Table", etc. If this is not given, and LABEL is, any cross referencing will simply use a bare number. LABEL Specifies a cross reference label for this float. If given, this float is automatically given a number, and will appear in any '@listoffloats' output (*note @listoffloats::). Cross references to LABEL are allowed. On the other hand, if LABEL is not given, then the float will not be numbered and consequently will not appear in the '@listoffloats' output or be cross-referenceable. Ordinarily, you specify both TYPE and LABEL, to get a labeled and numbered float. In Texinfo, all floats are numbered in the same way: with the chapter number (or appendix letter), a period, and the float number, which simply counts 1, 2, 3, ..., and is reset at each chapter. Each float type is counted independently. Floats within an '@unnumbered', or outside of any chapter, are simply numbered consecutively from 1. These numbering conventions are not, at present, changeable.  File: texinfo.info, Node: @caption @shortcaption, Next: @listoffloats, Prev: @float, Up: Floats 12.1.2 '@caption' & '@shortcaption' ----------------------------------- You may write an '@caption' anywhere within an '@float' environment, to define a caption for the float. It is not allowed in any other context. '@caption' takes a single argument, enclosed in braces. Here's an example: @float An example float, with caption. @caption{Caption for example float.} @end float The output is: An example float, with caption. Caption for example float. '@caption' can appear anywhere within the float; it is not processed until the '@end float'. The caption text is usually a sentence or two, but may consist of several paragraphs if necessary. In the output, the caption always appears below the float; this is not currently changeable. It is preceded by the float type and/or number, as specified to the '@float' command (see the previous section). The '@shortcaption' command likewise may be used only within '@float', and takes a single argument in braces. The short caption text is used instead of the caption text in a list of floats (see the next section). Thus, you can write a long caption for the main document, and a short title to appear in the list of floats. For example: @float ... as above ... @shortcaption{Text for list of floats.} @end float The text for '@shortcaption' may not contain comments ('@c'), verbatim text ('@verb'), environments such as '@example', footnotes ('@footnote') or other complex constructs. The same constraints apply to '@caption' unless there is an '@shortcaption'.  File: texinfo.info, Node: @listoffloats, Prev: @caption @shortcaption, Up: Floats 12.1.3 '@listoffloats': Tables of Contents for Floats ----------------------------------------------------- You can write an '@listoffloats' command to generate a list of floats for a given float type (*note @float::), analogous to the document's overall table of contents. Typically, it is written in its own '@unnumbered' node to provide a heading and structure, rather like '@printindex' (*note Printing Indices & Menus::). '@listoffloats' takes one optional argument, the float type. Here's an example: @node List of Figures @unnumbered List of Figures @listoffloats Figure And here's what the output from '@listoffloats' looks like, given the example figure earlier in this chapter (the Info output is formatted as a menu): * Figure 12.1: fig:ex1. Without any argument, '@listoffloats' generates a list of floats for which no float type was specified, i.e., no first argument to the '@float' command (*note @float::). Each line in the list of floats contains the float type (if any), the float number, and the caption, if any--the '@shortcaption' argument, if it was specified, else the '@caption' argument. In Info, the result is a menu where each float can be selected. In HTML, each line is a link to the float. In printed output, the page number is included. Unnumbered floats (those without cross reference labels) are omitted from the list of floats.  File: texinfo.info, Node: Images, Next: Footnotes, Prev: Floats, Up: Special Displays 12.2 Inserting Images ===================== You can insert an image given in an external file with the '@image' command. Although images can be used anywhere, including the middle of a paragraph, we describe them in this chapter since they are most often part of a displayed figure or example. * Menu: * Image Syntax:: * Image Scaling::  File: texinfo.info, Node: Image Syntax, Next: Image Scaling, Up: Images 12.2.1 Image Syntax ------------------- Here is the synopsis of the '@image' command: @image{FILENAME[, WIDTH[, HEIGHT[, ALTTEXT[, EXTENSION]]]]} The FILENAME argument is mandatory, and must not have an extension, because the different processors support different formats: * TeX (DVI output) reads the file 'FILENAME.eps' (Encapsulated PostScript format). * pdfTeX reads 'FILENAME.pdf', 'FILENAME.png', 'FILENAME.jpg', or 'FILENAME.jpeg' (in that order). It also tries uppercase versions of the extensions. The PDF format does not support EPS images, so such must be converted first. * For Info, 'makeinfo' includes 'FILENAME.txt' verbatim (more or less as if it were in '@verbatim'). The Info output may also include a reference to 'FILENAME.png' or 'FILENAME.jpg'. (See below.) * For HTML, 'makeinfo' outputs a reference to 'FILENAME.png', 'FILENAME.jpg', 'FILENAME.jpeg' or 'FILENAME.gif' (in that order). If none of those exist, it gives an error, and outputs a reference to 'FILENAME.jpg' anyway. * For Docbook, 'makeinfo' outputs references to 'FILENAME.eps', 'FILENAME.gif' 'FILENAME.jpeg', 'FILENAME.jpg', 'FILENAME.pdf', 'FILENAME.png' and 'FILENAME.svg', for every file found. Also, 'FILENAME.txt' is included verbatim, if present. (The subsequent Docbook processor is supposed to choose the appropriate one.) * For Info and HTML output, 'makeinfo' uses the optional fifth argument EXTENSION to '@image' for the filename extension, if it is specified and the file is found. Any leading period should be included in EXTENSION. For example: @image{foo,,,,.xpm} If you want to install image files for use by Info readers too, we recommend putting them in a subdirectory like 'FOO-figures' for a package FOO. Copying the files into '$(infodir)/FOO-figures/' should be done in your 'Makefile'. The WIDTH and HEIGHT arguments are described in the next section. For TeX output, if an image is the only thing in a paragraph it will ordinarily be displayed on a line by itself, respecting the current environment indentation, but without the normal paragraph indentation. If you want it centered, use '@center' (*note @titlefont @center @sp::). For HTML output, 'makeinfo' sets the "alt attribute" for inline images to the optional ALTTEXT (fourth) argument to '@image', if supplied. If not supplied, 'makeinfo' uses the full file name of the image being displayed. The ALTTEXT is processed as Texinfo text, so special characters such as '"' and '<' and '&' are escaped in the HTML output; also, you can get an empty 'alt' string with '@-' (a command that produces no output; *note @- @hyphenation::). For Info output, the 'alt' string is also processed as Texinfo text and output. In this case, '\' is escaped as '\\' and '"' as '\"'; no other escapes are done. In Info output, 'makeinfo' writes a reference to the binary image file (trying FILENAME suffixed with 'EXTENSION', '.EXTENSION', '.png', or '.jpg', in that order) if one exists. It also literally includes the '.txt' file if one exists. This way, Info readers which can display images (such as the Emacs Info browser, running under X) can do so, whereas Info readers which can only use text (such as the standalone Info reader) can display the textual version. The implementation of this is to put the following construct into the Info output: ^@^H[image src="BINARYFILE" text="TXTFILE" alt="ALTTEXT ... ^@^H] where '^@' and '^H' stand for the actual null and backspace control characters. If one of the files is not present, the corresponding argument is omitted. The reason for mentioning this here is that older Info browsers (this feature was introduced in Texinfo version 4.6) will display the above literally, which, although not pretty, should not be harmful.  File: texinfo.info, 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 which to scale the image. They are only taken into account in TeX. 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 likely 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 , 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.info, 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 at most, and it is best to avoid them completely. Standard bibliographical references are usually better placed in a bibliography at the end of a document instead of 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.info, 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, this 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. (Another style, perfectly acceptable, is to put the footnote after punctuation belonging to the sentence, as in ';@footnote{...'.) 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 text if footnotes are put in separate nodes (*note Footnote Styles::). In the HTML output, footnote references are generally marked with a small, superscripted number which is rendered as a hypertext link to the footnote text. Footnotes cannot be nested, and cannot appear in section headings of any kind or other "unusual" places. A final tip: footnotes in the argument of an '@item' command for an '@table' must be entirely on the same line as the '@item' (as usual). *Note Two-column Tables::. ---------- Footnotes ---------- (1) Here is the sample footnote.  File: texinfo.info, 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 the Info output for 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. (You should include any '@footnotestyle' command between the start-of-header and end-of-header lines, so the region formatting commands will format footnotes as specified.) In HTML, when the footnote style is 'end', or if the output is not split, footnotes are put at the end of the output. If set to 'separate', and the output is split, they are placed in a separate file.  File: texinfo.info, 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.info, 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 "Indices" are 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 skilled art, the subtleties of which may not be 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.info, 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.info, 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 devise entries which are terse yet clear. If you can do this, the index usually looks better if the entries are written just as they would appear in the middle of a sentence, that is, capitalizing only proper names and acronyms that always call for uppercase 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. Whichever case convention you use, use it consistently. In any event, do not ever capitalize a case-sensitive name such as a C or Lisp function name or a shell command; that would be a spelling error. Entries in indices other than the concept index are symbol names in programming languages, or program names; these names are usually case-sensitive, so likewise use upper- and lowercase as required. It is a good idea to make index entries unique wherever feasible. That way, people using the printed output or online completion of index entries don't see undifferentiated lists. Consider this an opportunity to make otherwise-identical index entries be more specific, so readers can more easily find the exact place they are looking for. Index entries should precede the visible material that is being indexed. For instance: @cindex hello Hello, there! Among other reasons, that way following indexing links (in whatever context) ends up before the material, where readers want to be, instead of after. 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.info, 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 roman font for the merged-from index.  File: texinfo.info, Node: @syncodeindex, Next: @synindex, Up: Combining Indices 13.4.1 '@syncodeindex': Combining indices using '@code' ------------------------------------------------------- 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.info, Node: @synindex, Prev: @syncodeindex, Up: Combining Indices 13.4.2 '@synindex': Combining indices ------------------------------------- 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.info, Node: New Indices, Prev: Combining Indices, Up: Indices 13.5 Defining New Indices ========================= In addition to the predefined indices (*note 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 New index names are usually two-letter words, 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".) 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::). As mentioned earlier (*note Predefined 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. When creating an index, TeX creates a file whose extension is the name of the index (*note Names of index files::). Therefore you should avoid using index names that collide with extensions used for other purposes, such as '.aux' or '.xml'. 'makeinfo' already reports an error if a new index conflicts well-known extension name.  File: texinfo.info, 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: * Special Characters:: Inserting @ {} , \ # * Inserting Quote Characters:: Inserting left and right quotes, in code. * Inserting Space:: Inserting the right amount of whitespace. * Inserting Accents:: Inserting accents and special characters. * Inserting Quotation Marks:: Inserting quotation marks. * Inserting Subscripts and Superscripts:: Inserting sub/superscripts. * Inserting Math:: Formatting mathematical expressions. * Glyphs for Text:: Inserting dots, bullets, currencies, etc. * Glyphs for Programming:: Indicating results of evaluation, expansion of macros, errors, etc. * Inserting Unicode:: Inserting a Unicode character by code point.  File: texinfo.info, Node: Special Characters, Next: Inserting Quote Characters, Up: Insertions 14.1 Special Characters: Inserting @ {} , \ # ============================================= '@' and curly braces are the basic 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. Alphabetic commands are also provided. The other characters (comma, backslash, hash) are special only in restricted contexts, as explained in the respective sections. * Menu: * Inserting an Atsign:: '@@', '@atchar{}'. * Inserting Braces:: '@{ @}', '@l rbracechar{}'. * Inserting a Comma:: , and '@comma{}'. * Inserting a Backslash:: \ and '@backslashchar{}'. * Inserting a Hashsign:: # and '@hashchar{}'.  File: texinfo.info, Node: Inserting an Atsign, Next: Inserting Braces, Up: Special Characters 14.1.1 Inserting '@' with '@@' and '@atchar{}' ---------------------------------------------- '@@' produces a single '@' character in the output. Do not put braces after an '@@' command. '@atchar{}' also produces a single '@' character in the output. It does need following braces, as usual for alphabetic commands. In inline conditionals (*note Inline Conditionals::), it can be necessary to avoid using the literal '@' character in the source (and may be clearer in other contexts).  File: texinfo.info, Node: Inserting Braces, Next: Inserting a Comma, Prev: Inserting an Atsign, Up: Special Characters 14.1.2 Inserting '{ '}' with '@{ @}' and '@l rbracechar{}' ---------------------------------------------------------- '@{' produces a single '{' in the output, and '@}' produces a single '}'. Do not put braces after either an '@{' or an '@}' command. '@lbracechar{}' and '@rbracechar{}' also produce single '{' and '}' characters in the output. They do need following braces, as usual for alphabetic commands. In inline conditionals (*note Inline Conditionals::), it can be necessary to avoid using literal brace characters in the source (and may be clearer in other contexts).  File: texinfo.info, Node: Inserting a Comma, Next: Inserting a Backslash, Prev: Inserting Braces, Up: Special Characters 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 only in one context: to separate arguments to those Texinfo commands, such as '@acronym' (*note @acronym::) and '@xref' (*note Cross References::), as well as user-defined macros (*note Defining Macros::), which take more than one argument. 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 '@comma{}' can be used nearly anywhere, there is no need for it anywhere except in this unusual case. (Incidentally, the name '@comma' lacks the 'char' suffix used in its companion commands only for historical reasons. It didn't seem important enough to define a synonym.)  File: texinfo.info, Node: Inserting a Backslash, Next: Inserting a Hashsign, Prev: Inserting a Comma, Up: Special Characters 14.1.4 Inserting '\' with '@backslashchar{}' -------------------------------------------- Ordinarily, a backslash '\' is a normal character in Texinfo that can be simply typed in your input where you need it. The result is to typeset the backslash from the typewriter font. However, Texinfo uses the backslash as a special character in one restricted context: to delimit formal arguments in the bodies of user-defined macros (*note Defining Macros::). Due to the vagaries of macro argument parsing, it is more reliable to pass an alphabetic command that produces a backslash instead of using a literal \. Hence '@backslashchar{}'. Here is an example macro call: @mymac{One argument@backslashchar{} with a backslash} Texinfo documents may also use \ as a command character inside '@math' (*note Inserting Math::). In this case, '@\' or '\backslash' produces a "math" backslash (from the math symbol font), while '@backslashchar{}' produces a typewriter backslash as usual. Although '@backslashchar{}' can be used nearly anywhere, there is no need for it except in these unusual cases.  File: texinfo.info, Node: Inserting a Hashsign, Prev: Inserting a Backslash, Up: Special Characters 14.1.5 Inserting '#' with '@hashchar{}' --------------------------------------- Ordinarily, a hash '#' is a normal character in Texinfo that can be simply typed in your input where you need it. The result is to typeset the hash character from the current font. This character has many other names, varying by locale, such as "number sign", "pound", and "octothorp". It is also sometimes called "sharp" or "sharp sign" since it vaguely resembles the musical symbol by that name. In situations where Texinfo is used, "hash" is the most common in our experience. However, Texinfo uses the hash character as a special character in one restricted context: to introduce the so-called '#line' directive and variants (*note External Macro Processors::). So, in order to typeset an actual hash character in such a place (for example, in a program that needs documentation about '#line'), it's necessary to use '@hashchar{}' or some other construct. Here's an example: @hashchar{} 10 "example.c" Although '@hashchar{}' can be used nearly anywhere, there is no need for it anywhere except this unusual case.  File: texinfo.info, Node: Inserting Quote Characters, Next: Inserting Space, Prev: Special Characters, 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 you, Texinfo provides these two commands: '@codequoteundirected ON-OFF' causes the output for the ''' character in code environments to be the undirected single quote, like this: '''. '@codequotebacktick ON-OFF' causes the output for the '`' character in code environments to be the backtick character (standalone grave accent), like this: '`'. If you want these settings for only part of the document, '@codequote... off' will restore the normal behavior, as in '@codequoteundirected off'. These settings affect '@code', '@example', '@kbd', '@samp', '@verb', and '@verbatim'. *Note Useful Highlighting::. This feature used to be controlled by using '@set' to change the values of the corresponding variables 'txicodequoteundirected' and 'txicodequotebacktick'; they are still supported, but the command interface is preferred.  File: texinfo.info, 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: * Multiple Spaces:: Inserting multiple spaces. * Not Ending a Sentence:: Sometimes a . doesn't end a sentence. * Ending a Sentence:: Sometimes it does. * @frenchspacing:: Specifying end-of-sentence spacing. * @dmn:: Formatting a dimension.  File: texinfo.info, Node: Multiple Spaces, Next: Not Ending a Sentence, Up: Inserting Space 14.3.1 Multiple Spaces ---------------------- Ordinarily, multiple whitespace characters (space, tab, and newline) are collapsed into a single space. Occasionally, you may want to produce several consecutive spaces, either for purposes of example (e.g., 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., '@ ', 'TAB' represents an actual tab character, and '@NL' represents an '@' 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::.  File: texinfo.info, Node: Not Ending a Sentence, Next: Ending a Sentence, Prev: Multiple Spaces, Up: Inserting Space 14.3.2 Not Ending a Sentence ---------------------------- Depending on whether a period or exclamation point or question mark is inside or at the end of a sentence, slightly less or more space is inserted after a period in a typeset manual. Since it is not always possible to determine automatically when a period ends a sentence, 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: 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 (lowercase) abbreviations which are not at the ends of sentences. Also, when a parenthetical remark in the middle of a sentence (like this one!) ends with a period, exclamation point, or question mark, '@:' should be used after the right parenthesis. Similarly for right brackets and right quotes (both single and double). For example, foo vs.@: bar (or?)@: baz foo vs. bar (or?) baz produces foo vs. bar (or?) baz foo vs. bar (or?) baz '@:' has no effect on the HTML or Docbook output. Do not put braces after '@:' (or any non-alphabetic command). A few Texinfo commands force normal interword spacing, so that you don't have to insert '@:' where you otherwise would. These are the code-like highlighting commands, '@var', '@abbr', and '@acronym' (*note Useful Highlighting::). For example, in '@code{foo. bar}' the period is not considered the end of a sentence, and no extra space is inserted.  File: texinfo.info, Node: Ending a Sentence, Next: @frenchspacing, Prev: Not Ending a Sentence, Up: Inserting Space 14.3.3 Ending a Sentence ------------------------ As mentioned above, Texinfo normally inserts additional space after the end of a sentence. It uses the same heuristic for this as TeX: a sentence ends with a period, exclamation point, or question mark, either preceded or followed by optional closing punctuation, and then whitespace, and _not_ preceded by a capital letter. Use '@.' instead of a period, '@!' instead of an exclamation point, and '@?' instead of a question mark at the end of a sentence that does end with a capital letter. Do not put braces after any of these commands. For 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. The output follows. In printed output and Info, you can see the desired extra whitespace after the 'W' in the first line. 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 HTML output, '@.' is equivalent to a simple '.'; likewise for '@!' and '@?'. The "closing punctuation" mentioned above is defined as a right parenthesis (')', right bracket (']'), or right quote, either single or double (''' and ''''; the many possible additional Unicode right quotes are not included). These characters can be thought of as invisible with respect to whether a given period ends a sentence. (This is the same rule as TeX.) For instance, the periods in 'foo.) Bar' and 'foo.'' Bar' do end sentences. The meanings of '@:' and '@.', etc. in Texinfo are designed to work well with the Emacs sentence motion commands (*note (emacs)Sentences::). A few Texinfo commands are not considered as being an abbreviation, even though they may end with a capital letter when expanded, so that you don't have to insert '@.' and companions. Notably, this is the case for code-like highlighting commands, '@var' arguments ending with a capital letter, '@LaTeX', and '@TeX'. For example, that sentence ended with '... @code{@@TeX}.'; '@.' was not needed. Similarly, in '... @var{VARNAME}. Text' the period after VARNAME ends the sentence; there is no need to use '@.'.  File: texinfo.info, Node: @frenchspacing, Next: @dmn, Prev: Ending a Sentence, 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. This is the default in Texinfo (implemented in Info and printed output; for HTML, we don't try to override the browser). In French typography (and 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: This is text. Two sentences. Three sentences. French spacing. This is text. Two sentences. Three sentences. Non-French spacing. '@frenchspacing' also affects the output after '@.', '@!', and '@?' (*note Ending a Sentence::). '@frenchspacing' has no effect on the HTML or Docbook output; for XML, it outputs a transliteration of itself (*note Output Formats::).  File: texinfo.info, Node: @dmn, Prev: @frenchspacing, Up: Inserting Space 14.3.5 '@dmn'{DIMENSION}: Format a Dimension -------------------------------------------- You can use the '@dmn' command to format a dimension with a little extra space in the printed output. That is, on seeing '@dmn', TeX inserts just enough space for proper typesetting; in other output formats, the formatting commands insert no space at all. 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'. In these cases, however, you need to use '@tie' (*note @tie::) or '@w' (*note @w::) so that no line break can occur between the number and the dimension. Also, if you write a period after an abbreviation within a sentence (as with the 'in.' above), you should write '@:' after the period to prevent TeX from inserting extra whitespace, as shown here. *Note Not Ending a Sentence::.  File: texinfo.info, 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::). 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 @ogonek{a} a; ogonek @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< caron/hacek/check 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 @dh{} @DH{} d D Icelandic eth @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 @th{} @TH{} th TH Icelandic thorn  File: texinfo.info, Node: Inserting Quotation Marks, Next: Inserting Subscripts and Superscripts, 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::.) 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 , 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 (). 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 incorrect; a "guillemot" is a bird species (a type of auk). Traditions for quotation mark usage vary to a great extent between languages (). Texinfo does not provide commands or configurations 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::) 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 the glyph produced by '@quotedblleft', which is counter-intuitive. Thus, in this case the following aliases would be convenient: @alias lgqq = quotedblbase @alias rgqq = quotedblleft  File: texinfo.info, Node: Inserting Subscripts and Superscripts, Next: Inserting Math, Prev: Inserting Quotation Marks, Up: Insertions 14.6 '@sub' and '@sup': Inserting Subscripts and Superscripts ============================================================= You can insert subscripts and superscripts, in either text or math, with the '@sub' and '@sup' commands. (For other mathematical expressions, see the next section.) For example, here is a purely textual subscript and superscript: here@sub{below}@sup{above} produces: here_{below}^{above} Inside '@math', '@sub' and '@sup' produce mathematical subscripts and superscripts. This uses a different font in the TeX output (math italic instead of text italic); it makes no difference in the other output formats. Here's an example: @math{e@sup{x}} produces: e^{x} In Info and plain text, regardless of being used inside '@math', '@sub{TEXT}' is output as '_{TEXT}' and '@sup{TEXT}' as '^{TEXT}', including the literal braces (to mark the beginning and end of the "script" text to the reader). When the output format (and display program) permit (TeX math, HTML), the superscript is set above the subscript when both commands are given consecutively.  File: texinfo.info, Node: Inserting Math, Next: Glyphs for Text, Prev: Inserting Subscripts and Superscripts, Up: Insertions 14.7 '@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) = (b + a)} This produces the following in Info and HTML: (a + b) = (b + a) 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 use produce good mathematical formatting in any way (no use of MathML, etc.). The HTML output is enclosed by '...', but nothing more. However, as far as the TeX output is concerned, plain TeX mathematical commands are allowed in '@math', starting with '\'. In essence, '@math' switches into plain TeX math mode. (Exception: the plain TeX command '\sup', which typesets the mathematical operator name 'sup', must be accessed as '\mathopsup', due to the conflict with Texinfo's '@sup' command.) This allows you 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. The '@sub' and '@sup' commands described in the previous section produce subscripts and superscripts in HTML output as well as TeX; the plain TeX characters '_' and '^' for subscripts and superscripts are recognized by TeX inside '@math', but do nothing special in HTML or other output formats. It's best to use '\' instead of '@' for any such mathematical commands; otherwise, 'makeinfo' will complain. On the other hand, 'makeinfo' does allow input with matching (but unescaped) braces, such as 'k_{75}'; it complains about such 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 two characters '\\' in Info). '@\' is not defined outside of '@math', since a '\' ordinarily produces a literal (typewriter) '\'. You can also use '@backslashchar{}' in any mode to get a typewriter backslash. *Note Inserting a Backslash::. For displayed equations, you must at present use TeX directly (*note Raw Formatter Commands::).  File: texinfo.info, Node: Glyphs for Text, Next: Glyphs for Programming, Prev: Inserting Math, Up: Insertions 14.8 Glyphs for Text ==================== Texinfo has support for a few additional glyphs that are commonly used in printed text but not available in ASCII. Of course, there are many thousands more. It is possible to use Unicode characters as-is as far as 'makeinfo' is concerned, but TeX is not so lucky. * Menu: * @TeX @LaTeX:: The TeX logos. * @copyright:: The copyright symbol (c in a circle). * @registeredsymbol:: The registered symbol (R in a circle). * @dots:: How to insert ellipses: ... and ... * @bullet:: How to insert a bullet: * * @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.  File: texinfo.info, Node: @TeX @LaTeX, Next: @copyright, Up: Glyphs for Text 14.8.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 for Texinfo, in that they use both uppercase and lowercase letters.  File: texinfo.info, Node: @copyright, Next: @registeredsymbol, Prev: @TeX @LaTeX, Up: Glyphs for Text 14.8.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)'. Legally, it's not necessary to use the copyright symbol; the English word 'Copyright' suffices, according to international treaty.  File: texinfo.info, Node: @registeredsymbol, Next: @dots, Prev: @copyright, Up: Glyphs for Text 14.8.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.info, Node: @dots, Next: @bullet, Prev: @registeredsymbol, Up: Glyphs for Text 14.8.4 '@dots' (...) and '@enddots' (...) ----------------------------------------- An "ellipsis" (a sequence of dots) would be spaced wrong when typeset as a string of periods, so a special command is used in Texinfo: use the '@dots{}' command to generate a normal ellipsis, which is three dots in a row, appropriately spaced ... like so. To emphasize: 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. The '@enddots{}' command generates an end-of-sentence ellipsis, which also has three dots, but with different spacing afterwards, ... Look closely to see the difference. Here is an ellipsis: ... Here are three periods in a row: ... In printed (and usually HTML) output, the three periods in a row are much closer together than the dots in the ellipsis.  File: texinfo.info, Node: @bullet, Next: @euro, Prev: @dots, Up: Glyphs for Text 14.8.5 '@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::).  File: texinfo.info, Node: @euro, Next: @pounds, Prev: @bullet, Up: Glyphs for Text 14.8.6 '@euro' (Euro): Euro Currency Symbol ------------------------------------------- Use the '@euro{}' command to generate 'Euro'. Where possible, this is the symbol for the Euro currency. Otherwise, the word 'Euro' is used. Texinfo cannot magically synthesize support for the Euro symbol where the underlying system (fonts, software, whatever) does not support it. Therefore, you may find it preferable to use the word "Euro". (In banking contexts, 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' or '@documentencoding UTF-8' (*Note @documentencoding::.) The Euro symbol is in ISO 8859-15 (aka Latin 9), and is _not_ in the more widely-used 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 , among other places. The distribution includes installation instructions.  File: texinfo.info, Node: @pounds, Next: @textdegree, Prev: @euro, Up: Glyphs for Text 14.8.7 '@pounds' (#): Pounds Sterling ------------------------------------- Use the '@pounds{}' command to generate '#'. Where possible, this is the symbol for the pounds sterling British currency. Otherwise, it is '#'.  File: texinfo.info, Node: @textdegree, Next: @minus, Prev: @pounds, Up: Glyphs for Text 14.8.8 '@textdegree' (o): Degrees Symbol ---------------------------------------- Use the '@textdegree{}' command to generate 'o'. Where possible, this is the normal symbol for degrees. Otherwise, it is an 'o'.  File: texinfo.info, Node: @minus, Next: @geq @leq, Prev: @textdegree, Up: Glyphs for Text 14.8.9 '@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::). If you actually want to typeset some math that does a subtraction, it is better to use '@math'. Then the regular '-' character produces a minus sign, as in '@math{a-b}' (*note Inserting Math::).  File: texinfo.info, Node: @geq @leq, Prev: @minus, Up: Glyphs for Text 14.8.10 '@geq' (>=) and '@leq' (<=): Inserting Relations -------------------------------------------------------- Use the '@geq{}' and '@leq{}' commands to generate greater-than-or-equal and less-than-equal-signs, '>=' and '<='. When those symbols are not available, the ASCII sequences '>=' and '<=' are output.  File: texinfo.info, Node: Glyphs for Programming, Next: Inserting Unicode, Prev: Glyphs for Text, Up: Insertions 14.9 Glyphs for Programming =========================== 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, the location of point in an editor, and GUI operation sequences. The glyph-insertion commands do not need to be used within an example, but most often they are. All glyph-insertion commands are followed by empty braces. * Menu: * Glyphs Summary:: * @result:: How to show the result of expression. * @expansion:: How to indicate an expansion. * @print:: How to indicate generated output. * @error:: How to indicate an error message. * @equiv:: How to indicate equivalence. * @point:: How to indicate the location of point. * Click Sequences:: Inserting GUI usage sequences.  File: texinfo.info, Node: Glyphs Summary, Next: @result, Up: Glyphs for Programming 14.9.1 Glyphs Summary --------------------- Here is a summary of the glyph commands: => '@result{}' indicates the result of an expression. ==> '@expansion{}' indicates the results of a macro expansion. -| '@print{}' indicates printed output. error-> '@error{}' indicates the following text is an error message. == '@equiv{}' indicates the exact equivalence of two forms. -!- '@point{}' shows the location of point. A -> B '@clicksequence{A @click{} B' indicates a GUI operation sequence: first A, then clicking B, or choosing B from a menu, or otherwise selecting it.  File: texinfo.info, Node: @result, Next: @expansion, Prev: Glyphs Summary, Up: Glyphs for Programming 14.9.2 '@result{}' (=>): Result of an Expression ------------------------------------------------ Use the '@result{}' command to indicate the result of evaluating an expression. The '@result{}' command is displayed as '=>', either a double stemmed arrow or (when that is not available) the ASCII sequence '=>'. Thus, the following, (cdr '(1 2 3)) => (2 3) may be read as "'(cdr '(1 2 3))' evaluates to '(2 3)'".  File: texinfo.info, Node: @expansion, Next: @print, Prev: @result, Up: Glyphs for Programming 14.9.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 '==>', either a long arrow with a flat base or (when that is not available) the ASCII sequence '==>'. 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.info, Node: @print, Next: @error, Prev: @expansion, Up: Glyphs for Programming 14.9.4 '@print{}' (-|): Indicating Generated Output --------------------------------------------------- Sometimes an expression will generate output during its execution. You can indicate such displayed output with the '@print{}' command. The '@print{}' command is displayed as '-|', either a horizontal dash butting against a vertical bar or (when that is not available) the ASCII sequence '-|'. 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.info, Node: @error, Next: @equiv, Prev: @print, Up: Glyphs for Programming 14.9.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->', either the word 'error' in a box in the printed output, the word error followed by an arrow in other formats or (when no arrow is available) 'error-->'. 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 The word 'error->' itself is not part of the error message.  File: texinfo.info, Node: @equiv, Next: @point, Prev: @error, Up: Glyphs for Programming 14.9.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 '==', either a standard mathematical equivalence sign (three parallel horizontal lines) or (when that is not available) as the ASCII sequence '=='. 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.info, Node: @point, Next: Click Sequences, Prev: @equiv, Up: Glyphs for Programming 14.9.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 '-!-', either a pointed star or (when that is not available) the ASCII sequence '-!-'. 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.info, Node: Click Sequences, Prev: @point, Up: Glyphs for Programming 14.9.8 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 right arrow 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::). 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.info, Node: Inserting Unicode, Prev: Glyphs for Programming, Up: Insertions 14.10 Inserting Unicode: '@U' ============================= The command '@U{HEX}' inserts a representation of the Unicode character U+HEX. For example, '@U{0132}' inserts the Dutch 'IJ' ligature (poorly shown here as simply the two letters 'I' and 'J'). The HEX value should be at least four hex digits; leading zeros are _not_ added. In general, HEX must specify a valid normal Unicode character; e.g., U+10FFFF (the very last code point) is invalid by definition, and thus cannot be inserted this way. '@U' is useful for inserting occasional glyphs for which Texinfo has no dedicated command, while allowing the Texinfo source to remain purely 7-bit ASCII for maximum portability. This command has many limitations--the same limitations as inserting Unicode characters in UTF-8 or another binary form. First and most importantly, TeX knows nothing about most of Unicode. Supporting specific additional glyphs upon request is possible, but it's not viable for 'texinfo.tex' to support whole additional scripts (Japanese, Urdu, ...). The '@U' command does nothing to change this. If the specified character is not supported in TeX, an error is given. (*Note @documentencoding::.) In HTML, XML, and Docbook, the output from '@U' is always an entity reference of the form '&#xHEX;', as in 'IJ' for the example above. This should work even when an HTML document uses some other encoding (say, Latin 1) and the given character is not supported in that encoding. In Info and plain text, if the document encoding is specified explicitly to be UTF-8, the output will be the UTF-8 representation of the character U+HEX (presuming it's a valid character). In all other cases, the output is the ASCII sequence 'U+HEX', as in the six ASCII characters 'U+0132' for the example above. That's all. No magic!  File: texinfo.info, Node: Breaks, Next: Definition Commands, Prev: Insertions, Up: Top 15 Forcing and Preventing Breaks ******************************** Line and page breaks can sometimes occur in the 'wrong' place in one or another form of output. It's up to you to ensure that text looks right in all the output formats. 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. You can use the break, break prevention, or pagination commands to fix problematic line and page breaks. * Menu: * Break Commands:: Summary of break-related commands. * Line Breaks:: Forcing line breaks. * @- @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.info, 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 other output formats do not have pages. '@page' Start a new page. '@group' Hold text together that must appear on one page. '@need MILS' Start a new page if not enough space on this one.  File: texinfo.info, Node: Line Breaks, Next: @- @hyphenation, Prev: Break Commands, Up: Breaks 15.2 '@*' and '@/': Generate and Allow Line Breaks ================================================== The '@*' command forces a line break in all output formats. The '@/' command allows a line break (printed manual only). Here is an example with '@*': This sentence is broken @*into two lines. produces This sentence is broken into two lines. The '@/' command can be useful within long urls or other identifiers where TeX can't find a good place to break. TeX will automatically break urls at the natural places (*note URL Line Breaking::), so only use '@/' if you need it. '@/' has no effect in the other output format.  File: texinfo.info, Node: @- @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.info, Node: @allowcodebreaks, Next: @w, Prev: @- @hyphenation, Up: Breaks 15.4 '@allowcodebreaks': Control Line Breaks in '@code' ======================================================= Ordinarily, TeX considers breaking lines at '-' and '_' characters within '@code' and related commands (*note @code::), more or less as if they were "empty" hyphenation points. This is necessary since many manuals, especially for Lisp-family languages, must document very long identifiers. On the other hand, some 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 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 except in HTML and TeX output.  File: texinfo.info, Node: @w, Next: @tie, Prev: @allowcodebreaks, Up: Breaks 15.5 '@w'{TEXT}: Prevent Line Breaks ==================================== '@w{TEXT}' outputs TEXT, while prohibiting line breaks within TEXT. 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); for that, 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$'. This trick isn't effective in Info or plain text output, though.  File: texinfo.info, 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.info, 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.info, 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. In other formats, without the concept of pages, it starts a new paragraph. An '@page' command is often used in the '@titlepage' section of a Texinfo file to start the copyright page.  File: texinfo.info, 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.info, 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 other output formats 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.info, Node: Definition Commands, Next: Internationalization, 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.info, 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.  File: texinfo.info, 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, in the same way; put an '@' at the end of each line to be continued. In general, any number of spaces or tabs before the '@' continuation character 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'. To avoid this, elide the unwanted whitespace in your input, or put the continuation '@' outside braces. '@' does not 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.info, 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, conventionally specified by using square brackets and ellipses: an argument enclosed within square brackets is optional, and an argument followed by an ellipsis is optional and may be repeated more than once. Thus, [OPTIONAL-ARG] means that OPTIONAL-ARG is optional and 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 (complicated) 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, including a continuation to avoid a long source line. @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.info, Node: @deffnx, Next: Def Cmds in Detail, Prev: Optional Arguments, Up: Definition Commands 16.4 '@deffnx', et al.: 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.info, 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.info, 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' 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 extremely unusual case when an argument name contains '--', or another character sequence which is treated specially (*note Conventions::), use '@code' around the special characters. This avoids the conversion to typographic en-dashes and em-dashes. 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 (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.info, 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. We recommend capitalizing 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 (emacs)Variables::). '@defopt' is equivalent to '@defvr {User Option} ...' and works like '@defvar'. It creates an entry in the index of variables.  File: texinfo.info, 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 produces: -- 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 (In these examples the '@deftypefn' arguments are shown using continuations (*note Def Cmd Continuation Lines::), but could be on a single line.) 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. Ordinarily, the return type is printed on the same line as the function name and arguments, as shown above. In source code, GNU style is to put the return type on a line by itself. So Texinfo provides an option to do that: '@deftypefnnewline on'. This affects typed functions only--not untyped functions, not typed variables, etc.. Specifically, it affects the commands in this section, and the analogous commands for object-oriented languages, namely '@deftypeop' and '@deftypemethod' (*note Object-Oriented Methods::). Specifying '@deftypefnnewline off' reverts to the default.  File: texinfo.info, 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: -- 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.info, 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.info, 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.info, 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.info, 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. The typed commands are affected by the '@deftypefnnewline' option (*note Functions in Typed Languages: Typed Functions.).  File: texinfo.info, 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.info, 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 (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.info, Node: Internationalization, Next: Conditionals, Prev: Definition Commands, Up: Top 17 Internationalization *********************** Texinfo has some support for writing in languages other than English, although this area still needs considerable work. (If you are yourself helping to translate the fixed strings written to documents, *note Internationalization of Document Strings::.) 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.info, Node: @documentlanguage, Next: @documentencoding, Up: Internationalization 17.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::): @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 (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 '@documentlanguage' argument contains the optional '_CC' suffix, this is tried first. For example, with '@documentlanguage 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. '@documentlanguage' also changes TeX's current hyphenation patterns, if the TeX program being run has the necessary support included. This will generally not be the case for 'tex' itself, but will usually be the case for up-to-date distributions of the extended TeX programs 'etex' (DVI output) and 'pdftex' (PDF output). 'texi2dvi' will use the extended TeXs if they are available (*note Format with texi2dvi::). In September 2006, the W3C Internationalization Activity released a new recommendation for specifying languages: . 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, . The country codes and the official web site for ISO 3166 can be found via .  File: texinfo.info, Node: @documentencoding, Prev: @documentlanguage, Up: Internationalization 17.2 '@documentencoding ENC': Set Input Encoding ================================================ The '@documentencoding' command declares the input document encoding, and can also affect the encoding of the output. Write it on a line by itself, with a valid encoding specification following, near the beginning of the file but after '@setfilename' (*note @setfilename::): @documentencoding ENC Texinfo supports 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. '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 . '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, a so-called 'Local Variables' section (*note (emacs)File Variables::) is output including ENC. This allows Info readers to set the encoding appropriately. It looks like this: Local Variables: coding: ENC End: Also, in Info and plain text output, unless the option '--disable-encoding' is given to 'makeinfo', accent constructs and special characters, such as '@'e', are output as the actual 8-bit or UTF-8 character in the given encoding where possible. 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. That looks like this: In XML and Docbook output, UTF-8 is always used for the output, according to the conventions of 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. Although modern TeX systems support nearly every script in use in the world, this wide-ranging support is not available in 'texinfo.tex', and it's not feasible to duplicate or incorporate all that effort. (Our plan to support other scripts is to create a LaTeX back-end to 'texi2any', where the support is already present.) For maximum portability of Texinfo documents across the many different user environments in the world, we recommend sticking to 7-bit ASCII in the input unless your particular manual needs a substantial amount of non-ASCII, e.g., it's written in German. You can use the '@U' command to insert an occasional needed character (*note Inserting Unicode::).  File: texinfo.info, Node: Conditionals, Next: Defining New Texinfo Commands, Prev: Internationalization, Up: Top 18 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 _excluding_ a given one (e.g., not Info, not TeX, ...). * 'Raw' formatter text for any output format, passed straight through with minimal (but not zero) 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. * Inline Conditionals:: Brace-delimited conditional text. * @set @clear @value:: Variable tests and substitutions. * Testing for Texinfo Commands:: Testing if a Texinfo command is available. * Conditional Nesting:: Using conditionals inside conditionals.  File: texinfo.info, Node: Conditional Commands, Next: Conditional Not Commands, Up: Conditionals 18.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, but without the special historical case: '@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. The newlines following the commands are (more or less) treated as whitespace, so that the conditional text is flowed normally into a surrounding paragraph. The '@if...' constructs are intended to conditionalize normal Texinfo source; *note Raw Formatter Commands::, for using underlying format commands directly. 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. In complex documents, you may want Texinfo to issue an error message in some conditionals that should not ever be processed. The '@errormsg{TEXT}' command will do this; it takes one argument, the text of the error message, which is expanded more or less as if it were Info text. We mention '@errormsg{}' here even though it is not strictly related to conditionals, since in practice it is most likely to be useful in that context. Technically, it can be used anywhere. *Note External Macro Processors::, for a caveat regarding the line numbers which '@errormsg' emits in TeX.  File: texinfo.info, Node: Conditional Not Commands, Next: Raw Formatter Commands, Prev: Conditional Commands, Up: Conditionals 18.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.info, Node: Raw Formatter Commands, Next: Inline Conditionals, Prev: Conditional Not Commands, Up: Conditionals 18.3 Raw Formatter Commands =========================== The '@if...' conditionals just described must be used only with normal Texinfo source. For instance, most features of plain TeX will not work within '@iftex'. The purpose of '@if...' is to provide conditional processing for Texinfo source, not provide access to underlying formatting features. For that, Texinfo provides so-called "raw formatter commands". They should only be used when truly required (most documents do not need them). The first raw formatter command is '@tex'. 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. Texinfo processors will not output material in 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. If you need to make several definitions, you may wish to set '\globaldefs=1' (its value will be restored to zero as usual when the group ends at '@end tex', so it won't cause problems with the rest of the document). As an example, here is a displayed equation 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 a format not generated by TeX, you will not see the equation that appears in the printed manual. Analogously, you can use '@ifhtml ... @end ifhtml' to delimit Texinfo source 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 Texinfo source to be included in XML output only, and '@xml ... @end xml' for a region of raw XML. Regions of raw text in other formats will also be present in the XML output, but with protection of XML characters and within corresponding elements. For example, the raw HTML text: @html
@end html will be included in the XML output as: <br /> Again likewise, you can use '@ifdocbook ... @end ifdocbook' to delimit Texinfo source to be included in Docbook output only, and '@docbook ... @end docbook' for a region of raw Docbook. The behavior of newlines in raw regions is unspecified. In all cases, in raw processing, '@' retains the same meaning as in the remainder of the document. Thus, the Texinfo processors must recognize and even execute, to some extent, the contents of the raw regions, regardless of the final output format. Therefore, specifying changes that globally affect the document inside a raw region leads to unpredictable and generally undesirable behavior. For example, using the '@kbdinputstyle' command inside a raw region is undefined. The remedy is simple: don't do that. Use the raw formatter commands for their intended purpose, of providing material directly in the underlying format. When you simply want to give different Texinfo specifications for different output formats, use the '@if...' conditionals and stay in Texinfo syntax.  File: texinfo.info, Node: Inline Conditionals, Next: @set @clear @value, Prev: Raw Formatter Commands, Up: Conditionals 18.4 Inline Conditionals: '@inline', '@inlineifelse', '@inlineraw' ================================================================== Texinfo provides a set of conditional commands with arguments given within braces: '@inlinefmt{FORMAT, TEXT}' Process the Texinfo TEXT if FORMAT output is being generated. '@inlinefmtifelse{FORMAT, THEN-TEXT, ELSE-TEXT}' Process the Texinfo THEN-TEXT if FORMAT output is being generated; otherwise, process ELSE-TEXT. '@inlineraw{FORMAT, TEXT}' Similar, but for raw TEXT (*note Raw Formatter Commands::). The supported FORMAT names are: docbook html info plaintext tex xml For example, @inlinefmt{html, @emph{HTML-only text}} is nearly equivalent to @ifhtml @emph{HTML-only text} @end ifhtml except that no whitespace is added, as happens in the latter (environment) case. In these commands, whitespace is ignored after the comma separating the arguments, as usual, but is _not_ ignored at the end of TEXT. To insert a literal at sign, left brace, or right brace in one of the arguments, you must use the alphabetic commands '@atchar{}' (*note Inserting an Atsign::), and '@lbracechar{}' or '@rbracechar{}' (*note Inserting Braces::), or the parsing will become confused. With '@inlinefmtifelse', it is also necessary to use '@comma{}' to avoid mistaking a ',' in the text for the delimiter. With '@inlinefmt' and '@inlineraw', '@comma{}' is not required (though it's fine to use it), since these commands always have exactly two arguments. For TeX, the processed TEXT cannot contain newline-delimited commands. Text to be ignored (i.e., for non-TeX) can, though. Two other '@inline...' conditionals complement the '@ifset' and '@ifclear' commands; see the next section.  File: texinfo.info, Node: @set @clear @value, Next: Testing for Texinfo Commands, Prev: Inline Conditionals, Up: Conditionals 18.5 Flags: '@set', '@clear', conditionals, 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. '@inlineifset{FLAG, TEXT}' Brace-delimited version of '@ifset'. '@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. '@inlineifclear{FLAG, TEXT}' Brace-delimited version of '@ifclear'. * Menu: * @set @value:: Expand a flag variable to a string. * @ifset @ifclear:: Format a region if a flag is set. * @inlineifset @inlineifclear:: Brace-delimited flag conditionals. * @value Example:: An easy way to update edition information.  File: texinfo.info, Node: @set @value, Next: @ifset @ifclear, Up: @set @clear @value 18.5.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") name is an identifier starting with an alphanumeric, '-', or '_'. Subsequent characters, if any, may not be whitespace, '@', braces, angle brackets, or any of '~`^+|'; other characters, such as '%', may work. However, it is best to use only letters and numerals in a flag name, not '-' or '_' or others--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. However, unlike most other commands which take the rest of the line as a value, '@set' need not appear at the beginning of a line. 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. '@value' cannot be reliably used as the argument to an accent command (*note Inserting Accents::). For example, this fails: @set myletter a @'@value{myletter}  File: texinfo.info, Node: @ifset @ifclear, Next: @inlineifset @inlineifclear, Prev: @set @value, Up: @set @clear @value 18.5.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.info, Node: @inlineifset @inlineifclear, Next: @value Example, Prev: @ifset @ifclear, Up: @set @clear @value 18.5.3 '@inlineifset' and '@inlineifclear' ------------------------------------------ '@inlineifset' and '@inlineifclear' provide brace-delimited alternatives to the '@ifset' and '@ifclear' forms, similar to the other '@inline...' Commands (*note Inline Conditionals::). The same caveats about argument parsing given there apply here too. '@inlineifset{VAR, TEXT}' Process the Texinfo TEXT if the flag VAR is defined. '@inlineifclear{VAR, TEXT}' Process the Texinfo TEXT if the flag VAR is not defined. Except for the syntax, their general behavior and purposes is the same as with '@ifset' and '@ifclear', described in the previous section.  File: texinfo.info, Node: @value Example, Prev: @inlineifset @inlineifclear, Up: @set @clear @value 18.5.4 '@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 (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 This is Edition @value{EDITION}, last updated @value{UPDATED}, of @cite{The GNU Make Manual}, for @code{make}, version @value{VERSION}. @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.info, Node: Testing for Texinfo Commands, Next: Conditional Nesting, Prev: @set @clear @value, Up: Conditionals 18.6 Testing for Texinfo Commands: '@ifcommanddefined', '@ifcommandnotdefined' ============================================================================== Occasionally, you may want to arrange for your manual to test if a given Texinfo command is available and (presumably) do some sort of fallback formatting if not. There are conditionals '@ifcommanddefined' and '@ifcommandnotdefined' to do this. For example: @ifcommanddefined node Good, @samp{@@node} is defined. @end ifcommanddefined will output the expected 'Good, '@node' is defined.'. This conditional will also consider true any new commands defined by the document via '@macro', '@alias', '@definfoenclose', and '@def(code)index' (*note Defining New Texinfo Commands::). Caveat: the TeX implementation reports internal TeX commands, in addition to all the Texinfo commands, as being "defined"; the 'makeinfo' implementation is reliable in this regard, however. You can check the 'NEWS' file in the Texinfo source distribution and linked from the Texinfo home page () to see when a particular command was added. These command-checking conditionals themselves were added in Texinfo 5.0, released in 2013--decades after Texinfo's inception. In order to test if they themselves are available, the predefined flag 'txicommandconditionals' can be tested, like this: @ifset txicommandconditionals @ifcommandnotdefined foobarnode (Good, '@foobarnode' is not defined.) @end ifcommandnotdefined @end ifset Since flags (see the previous section) were added early in the existence of Texinfo, there is no problem with assuming they are available. We recommend avoiding these tests whenever possible--which is usually the case. For many software packages, it is reasonable for all developers to have a given version of Texinfo (or newer) installed, and thus no reason to worry about older versions. (It is straightforward for anyone to download and install the Texinfo source; it does not have any problematic dependencies.) The issue of Texinfo versions does not generally arise for end-users. With properly distributed packages, users need not process the Texinfo manual simply to build and install the package; they can use preformatted Info (or other) output files. This is desirable in general, to avoid unnecessary dependencies between packages (*note (standards)Releases::).  File: texinfo.info, Node: Conditional Nesting, Prev: Testing for Texinfo Commands, Up: Conditionals 18.7 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.info, Node: Defining New Texinfo Commands, Next: Include Files, Prev: Conditionals, Up: Top 19 Defining New Texinfo Commands ******************************** Texinfo provides several ways to define new commands (in all cases, it's not recommended to try redefining existing 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 area 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 for all non-TeX output formats. Most generally of all (not just for defining new commands), it is possible to invoke any external macro processor and have Texinfo recognize so-called '#line' directives for error reporting. If you want to do simple text substitution, '@set' and '@value' is the simplest approach (*note @set @clear @value::). * 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. * External Macro Processors:: '#line' directives.  File: texinfo.info, 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 consisting of alphanumerics, and (except as the first character) '-'. The '_' character is excluded so that macros can be called inside '@math' without a following space (*note Inserting 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 macro invocations. However, 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 newline characters 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. However, there are still undesirable and unpredictable interactions between newlines, macros, and commands which are line-delimited, as warned about below (*note Macro Details::). 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.info, 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 "invoke" (use) it in your document like this: @MACRONAME {ARG1, ARG2, ...} and the result will be more or less 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 even when the macro takes no arguments, consistent with other Texinfo commands. For example: @macro argless {} No arguments here. @end macro @argless{} produces: No arguments here. Passing macro arguments containing commas requires special care, since commas also separate the arguments. To include a comma character in an argument, the most reliable method is to use the '@comma{}' command. For 'makeinfo', you can also prepend a backslash character, as in '\,', but this does not work with TeX. It's not always necessary to worry about commas. To facilitate use of macros, 'makeinfo' implements two rules for "automatic quoting" in some circumstances: 1. If a macro takes only one argument, all commas in its invocation are quoted by default. For example: @macro TRYME{text} @strong{TRYME: \text\} @end macro @TRYME{A nice feature, though it can be dangerous.} will produce the following output *TRYME: A nice feature, though it can be dangerous.* And indeed, it can. Namely, 'makeinfo' does not control the 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, for it to be treated as a part of an argument. In addition to the comma, 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. Unfortunately, this has not been reliably implemented in TeX. When macros are used in the argument to other commands, for example, errors or incorrect output (the '\' "escape" being included literally) are likely to result. If a macro is defined to take exactly one argument, it can (but need not) be invoked without any braces; then the entire rest of the line after the macro name is used as the argument. (Braces around the argument(s) are required in all other cases, i.e., if the macro takes either zero or more than one argument.) For example: @macro bar {p} Twice: \p\ & \p\. @end macro @bar aah produces: Twice: aah & aah. Likewise, if a macro is defined to take exactly one argument, and is invoked with braces, the braced text is passed as the argument, also regardless of commas. For example: @macro bar {p} Twice: \p\ & \p\. @end macro @bar{a,b} produces: Twice: a,b & a,b. If a macro is defined to take more than one argument, but is called with only one (in braces), the remaining arguments are set to the empty string, and no error is given. For example: @macro addtwo {p, q} Both: \p\\q\. @end macro @addtwo{a} produces simply: Both: a.  File: texinfo.info, Node: Macro Details, Next: @alias, Prev: Invoking Macros, Up: Defining New Texinfo Commands 19.3 Macro Details and Caveats ============================== By design, macro expansion does not happen in the following contexts in 'makeinfo': * '@macro' and '@unmacro' lines; * '@if...' lines, including '@ifset' and similar; * '@set', '@clear', '@value'; * '@clickstyle' lines; * '@end' lines. Unfortunately, TeX may do some expansion in these situations, possibly yielding errors. Also, quite a few macro-related constructs cause problems with TeX; some of the caveats are listed below. Thus, if you get macro-related errors when producing the printed version of a manual, you might try expanding the macros with 'makeinfo' by invoking 'texi2dvi' with the '-E' option (*note Format with texi2dvi::). Or, more reliably, eschew Texinfo macros altogether and use a language designed for macro processing, such as M4 (*note External Macro Processors::). * 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 large and open-ended set of names, and the possible resulting errors are unpredictable. * All macros are expanded inside at least one TeX group. * Macro arguments cannot cross lines. * 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. Similarly, macros containing line-oriented commands or text, such as '@example' environments, may behave unpredictably in TeX. * White space is ignored at the beginnings of lines. * Macros can't be reliably used in the argument to accent commands (*note Inserting Accents::). * The backslash escape for commas in macro arguments does not work; '@comma{}' must be used. * As a consequence, if a macro takes two or more arguments, and you want to pass an argument with the Texinfo command '@,' (to produce a cedilla, *note Inserting Accents::), you have to use '@value' or another work-around. Otherwise, TeX takes the comma as separating the arguments. Example: @macro mactwo{argfirst, argsecond} \argfirst\+\argsecond\. @end macro @set fc Fran@,cois @mactwo{@value{fc}} produces: Franc,ois+. The natural-seeming '@mactwo{Fran@,cois}' passes the two arguments 'Fran@' and 'cois' to the macro, and nothing good results. And, as just mentioned, although the comma can be escaped with a backslash for 'makeinfo' ('@\,'), that doesn't work in TeX, so there is no other solution. * It is usually best to avoid comments inside macro definitions, but see the next item. * In general, the interaction of newlines in the macro definitions and invocations depends on the precise commands and context, notwithstanding the previous statements. You may be able to work around some problems with judicious use of '@c' to "comment out" a newline, but '@c' will cause problems in other cases. We are unable to make any general statements. * In general, you can't arbitrarily substitute a macro (or '@value') call for Texinfo command arguments, even when the text is the same. Texinfo is not M4 (or even plain TeX). 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 This looks equivalent to '@headings off', but for TeXnical reasons, it fails with a mysterious error message (namely, '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 the following limitations (by design): * '@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 incompletely 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 that nested definition outside the macro. In the 'makeinfo' implementation before Texinfo 5.0, ends of lines from expansion of an '@macro' definition did not end an @-command line-delimited argument ('@chapter', '@center', etc.). This is no longer the case. For example: @macro twolines{} aaa bbb @end macro @center @twolines{} In the current 'makeinfo', this is equivalent to: @center aaa bbb with just 'aaa' as the argument to '@center'. In the earlier implementation, it would have been parsed as this: @center aaa bbb  File: texinfo.info, 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 additional 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 optional and ignored if present. 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. Unfortunately, it's not possible to alias Texinfo environments; for example, '@alias lang=example' is an error. Aliases must not be recursive, directly or indirectly. It is not advisable to redefine any TeX primitive, plain TeX, or Texinfo command name as an alias. Unfortunately this is a very large set of names, and the possible resulting errors from TeX are unpredictable. 'makeinfo' will accept the same identifiers for aliases as it does for macro names, that is, alphanumerics and (except as the first character) '-'.  File: texinfo.info, Node: @definfoenclose, Next: External Macro Processors, Prev: @alias, Up: Defining New Texinfo Commands 19.5 '@definfoenclose': Customized Highlighting =============================================== An '@definfoenclose' command may be used to define a highlighting command for all the non-TeX output formats. 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 output. Presumably, if you define a command with '@definfoenclose', you will create a corresponding command for TeX, either in 'texinfo.tex', 'texinfo.cnf', or within an '@iftex' of '@tex' in your document. Write an '@definfoenclose' command at the beginning of a line followed by three comma-separated arguments. The first argument to '@definfoenclose' is the @-command name (without the '@'); the second argument is the start delimiter string; and the third argument is the end delimiter string. The latter two arguments enclose the highlighted text in the output. 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 end delimiter string you intended will naturally be (mis)interpreted as the start delimiter string. If you do an '@definfoenclose' on the name of a predefined command (such as '@emph', '@strong', '@t', or '@i'), the enclosure definition will override the built-in definition. We don't recommend this. An enclosure command defined this way takes one argument in braces, since it 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. 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 everything else. The raw TeX commands need to be in '@iftex'. '@definfoenclose' command need not be within '@ifinfo', unless you want to use different definitions for different output formats. 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.info, Node: External Macro Processors, Prev: @definfoenclose, Up: Defining New Texinfo Commands 19.6 External Macro Processors: Line Directives =============================================== Texinfo macros (and its other text substitution facilities) work fine in straightforward cases. If your document needs unusually complex processing, however, their fragility and limitations can be a problem. In this case, you may want to use a different macro processor altogether, such as M4 (*note (m4)Top::) or CPP (*note (cpp)Top::). With one exception, Texinfo does not need to know whether its input is "original" source or preprocessed from some other source file. Therefore, you can arrange your build system to invoke whatever programs you like to handle macro expansion or other preprocessing needs. Texinfo does not offer built-in support for any particular preprocessor, since no one program seemed likely to suffice for the requirements of all documents. The one exception is line numbers in error messages. In that case, the line number should refer to the original source file, whatever it may be. There's a well-known mechanism for this: the so-called '#line' directive. Texinfo supports this. * Menu: * #line Directive:: * TeX: #line and TeX. * Syntax: #line Syntax Details.  File: texinfo.info, Node: #line Directive, Next: #line and TeX, Up: External Macro Processors 19.6.1 '#line' Directive ------------------------ An input line such as this: #line 100 "foo.ptexi" indicates that the next line was line 100 of the file 'foo.ptexi', and so that's what an error message should refer to. Both M4 (*note (m4)Preprocessor features::) and CPP (*note (cpp)Line Control::, and *note (cpp)Preprocessor Output::) can generate such lines. The 'makeinfo' program recognizes these lines by default, except within '@verbatim' blocks (*note @verbatim::. Their recognition can be turned off completely with 'CPP_LINE_DIRECTIVES' (*note Other Customization Variables::), though there is normally no reason to do so. For those few programs (M4, CPP, Texinfo) which need to document '#line' directives and therefore have examples which would otherwise match the pattern, the command '@hashchar{}' can be used (*note Inserting a Hashsign::). The example line above looks like this in the source for this manual: @hashchar{}line 100 "foo.ptexi" The '@hashchar' command was added to Texinfo in 2013. If you don't want to rely on it, you can also use '@set' and '@value' to insert the literal '#': @set hash # @value{hash}line 1 "example.c" Or, if suitable, an '@verbatim' environment can be used instead of '@example'. As mentioned above, '#line'-recognition is disabled inside verbatim blocks.  File: texinfo.info, Node: #line and TeX, Next: #line Syntax Details, Prev: #line Directive, Up: External Macro Processors 19.6.2 '#line' and TeX ---------------------- As mentioned, 'makeinfo' recognizes the '#line' directives described in the previous section. However, 'texinfo.tex' does not and cannot. Therefore, such a line will be incorrectly typeset verbatim if TeX sees it. The solution is to use 'makeinfo''s macro expansion options before running TeX. There are three approaches: * If you run 'texi2dvi' or its variants (*note Format with texi2dvi::), you can pass '-E' and 'texi2dvi' will run 'makeinfo' first to expand macros and eliminate '#line'. * If you run 'makeinfo' or its variants (*note Generic Translator texi2any::), you can specify '--no-ifinfo --iftex -E somefile.out', and then give 'somefile.out' to 'texi2dvi' in a separate command. * Or you can run 'makeinfo --dvi --Xopt -E'. (Or '--pdf' instead of '--dvi'.) 'makeinfo' will then call 'texi2dvi -E'. One last caveat regarding use with TeX: since the '#line' directives are not recognized, the line numbers emitted by the '@errormsg{}' command (*note Conditional Commands::), or by TeX itself, are the (incorrect) line numbers from the derived file which TeX is reading, rather than the preprocessor-specified line numbers. This is another example of why we recommend running 'makeinfo' for the best diagnostics (*note makeinfo Advantages::).  File: texinfo.info, Node: #line Syntax Details, Prev: #line and TeX, Up: External Macro Processors 19.6.3 '#line' Syntax Details ----------------------------- Syntax details for the '#line' directive: the '#' character can be preceded or followed by whitespace, the word 'line' is optional, and the file name can be followed by a whitespace-separated list of integers (these are so-called "flags" output by CPP in some cases). For those who like to know the gory details, the actual (Perl) regular expression which is matched is this: /^\s*#\s*(line)? (\d+)(( "([^"]+)")(\s+\d+)*)?\s*$/ As far as we've been able to tell, the trailing integer flags only occur in conjunction with a filename, so that is reflected in the regular expression. As an example, the following is a syntactically valid '#line' directive, meaning line 1 of '/usr/include/stdio.h': # 1 "/usr/include/stdio.h" 2 3 4 Unfortunately, the quoted filename ('"..."') has to be optional, because M4 (especially) can often generate '#line' directives within a single file. Since the 'line' is also optional, the result is that lines might match which you wouldn't expect, e.g., # 1 The possible solutions are described above (*note #line Directive::).  File: texinfo.info, Node: Include Files, Next: Hardcopy, Prev: Defining New Texinfo Commands, Up: Top 20 Include Files **************** When a Texinfo processor sees an '@include' command in a Texinfo file, it processes the contents of the file named by the '@include' and incorporates them into the output files being created. Include files thus let you keep a single large document as a collection of conveniently small parts. * Menu: * Using Include Files:: How to use the '@include' command. * texinfo-multiple-files-update:: How to create and update nodes and menus when using included files. * Include Files Requirements:: 'texinfo-multiple-files-update' needs. * Sample Include File:: A sample outer file with included files within it; and a sample included file. * Include Files Evolution:: How use of the '@include' command has changed over time.  File: texinfo.info, Node: Using Include Files, Next: texinfo-multiple-files-update, Up: Include Files 20.1 How to Use Include Files ============================= To include another file within a Texinfo file, write the '@include' command at the beginning of a line and follow it on the same line by the name of a file to be included. For example: @include buffers.texi @-commands are expanded in file names. The one most likely to be useful is '@value' (*note @set @value::), and even then only in complicated situations. An included file should simply be a segment of text that you expect to be included as is into the overall or "outer" Texinfo file; it should not contain the standard beginning and end parts of a Texinfo file. In particular, you should not start an included file with a line saying '\input texinfo'; if you do, that text is inserted into the output file literally. Likewise, you should not end an included file with an '@bye' command; nothing after '@bye' is formatted. In the long-ago past, you were required to write an '@setfilename' line at the beginning of an included file, but no longer. Now, it does not matter whether you write such a line. If an '@setfilename' line exists in an included file, it is ignored.  File: texinfo.info, Node: texinfo-multiple-files-update, Next: Include Files Requirements, Prev: Using Include Files, Up: Include Files 20.2 'texinfo-multiple-files-update' ==================================== GNU Emacs Texinfo mode provides the 'texinfo-multiple-files-update' command. This command creates or updates 'Next', 'Previous', and 'Up' pointers of included files as well as those in the outer or overall Texinfo file, and it creates or updates a main menu in the outer file. Depending on whether you call it with optional arguments, the command updates only the pointers in the first '@node' line of the included files or all of them: 'M-x texinfo-multiple-files-update' Called without any arguments: - Create or update the 'Next', 'Previous', and 'Up' pointers of the first '@node' line in each file included in an outer or overall Texinfo file. - Create or update the 'Top' level node pointers of the outer or overall file. - Create or update a main menu in the outer file. 'C-u M-x texinfo-multiple-files-update' Called with 'C-u' as a prefix argument: - Create or update pointers in the first '@node' line in each included file. - Create or update the 'Top' level node pointers of the outer file. - Create and insert a master menu in the outer file. The master menu is made from all the menus in all the included files. 'C-u 8 M-x texinfo-multiple-files-update' Called with a numeric prefix argument, such as 'C-u 8': - Create or update _all_ the 'Next', 'Previous', and 'Up' pointers of all the included files. - Create or update _all_ the menus of all the included files. - Create or update the 'Top' level node pointers of the outer or overall file. - And then create a master menu in the outer file. This is similar to invoking 'texinfo-master-menu' with an argument when you are working with just one file. Note the use of the prefix argument in interactive use: with a regular prefix argument, just 'C-u', the 'texinfo-multiple-files-update' command inserts a master menu; with a numeric prefix argument, such as 'C-u 8', the command updates _every_ pointer and menu in _all_ the files and then inserts a master menu.  File: texinfo.info, Node: Include Files Requirements, Next: Sample Include File, Prev: texinfo-multiple-files-update, Up: Include Files 20.3 Include Files Requirements =============================== If you plan to use the 'texinfo-multiple-files-update' command, the outer Texinfo file that lists included files within it should contain nothing but the beginning and end parts of a Texinfo file, and a number of '@include' commands listing the included files. It should not even include indices, which should be listed in an included file of their own. Moreover, each of the included files must contain exactly one highest level node (conventionally, '@chapter' or equivalent), and this node must be the first node in the included file. Furthermore, each of these highest level nodes in each included file must be at the same hierarchical level in the file structure. Usually, each is an '@chapter', an '@appendix', or an '@unnumbered' node. Thus, normally, each included file contains one, and only one, chapter or equivalent-level node. The outer file should contain only _one_ node, the 'Top' node. It should _not_ contain any nodes besides the single 'Top' node. The 'texinfo-multiple-files-update' command will not process them.  File: texinfo.info, Node: Sample Include File, Next: Include Files Evolution, Prev: Include Files Requirements, Up: Include Files 20.4 Sample File with '@include' ================================ Here is an example of an outer Texinfo file with '@include' files within it before running 'texinfo-multiple-files-update', which would insert a main or master menu: \input texinfo @c -*-texinfo-*- @setfilename include-example.info @settitle Include Example ... *Note Sample Texinfo Files::, for examples of the rest of the frontmatter ... @ifnottex @node Top @top Include Example @end ifnottex @include foo.texinfo @include bar.texinfo @include concept-index.texinfo @bye An included file, such as 'foo.texinfo', might look like this: @node First @chapter First Chapter Contents of first chapter ... The full contents of 'concept-index.texinfo' might be as simple as this: @node Concept Index @unnumbered Concept Index @printindex cp The outer Texinfo source file for 'The GNU Emacs Lisp Reference Manual' is named 'elisp.texi'. This outer file contains a master menu with 417 entries and a list of 41 '@include' files.  File: texinfo.info, Node: Include Files Evolution, Prev: Sample Include File, Up: Include Files 20.5 Evolution of Include Files =============================== When Info was first created, it was customary to create many small Info files on one subject. Each Info file was formatted from its own Texinfo source file. This custom meant that Emacs did not need to make a large buffer to hold the whole of a large Info file when someone wanted information; instead, Emacs allocated just enough memory for the small Info file that contained the particular information sought. This way, Emacs could avoid wasting memory. References from one file to another were made by referring to the file name as well as the node name. (*Note Referring to Other Info Files: Other Info Files. Also, see *note '@xref' with Four and Five Arguments: Four and Five Arguments.) Include files were designed primarily as a way to create a single, large printed manual out of several smaller Info files. In a printed manual, all the references were within the same document, so TeX could automatically determine the references' page numbers. The Info formatting commands used include files only for creating joint indices; each of the individual Texinfo files had to be formatted for Info individually. (Each, therefore, required its own '@setfilename' line.) However, because large Info files are now split automatically, it is no longer necessary to keep them small. Nowadays, multiple Texinfo files are used mostly for large documents, such as 'The GNU Emacs Lisp Reference Manual', and for projects in which several different people write different sections of a document simultaneously. In addition, the Info formatting commands have been extended to work with the '@include' command so as to create a single large Info file that is split into smaller files if necessary. This means that you can write menus and cross references without naming the different Texinfo files.  File: texinfo.info, Node: Hardcopy, Next: Generic Translator texi2any, Prev: Include Files, Up: Top 21 Formatting and Printing Hardcopy *********************************** Running the 'texi2dvi' or 'texi2pdf' command is the simplest way to create printable output. These commands are installed as part of the Texinfo package. In more detail, three major shell commands are used to print formatted output from a Texinfo manual: one converts the Texinfo source into something printable, a second sorts indices, and a third actually prints 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 (or some other computing environment). 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. Details are in the following sections. * Menu: * Use TeX:: Use TeX to format for hardcopy. * Format with texi2dvi:: The simplest way to format. * Format with tex/texindex:: Formatting with explicit shell commands. * 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.info, Node: Use TeX, Next: Format with texi2dvi, Up: Hardcopy 21.1 Use TeX ============ The typesetting program called TeX is used to format a Texinfo document for printable output. TeX is a very powerful typesetting program and, when used correctly, does an exceptionally good job. *Note Obtaining TeX::, for information on how to obtain TeX. It is not included in the Texinfo package, being a vast suite of software in itself.  File: texinfo.info, Node: Format with texi2dvi, Next: Format with tex/texindex, Prev: Use TeX, Up: Hardcopy 21.2 Format with 'texi2dvi' =========================== The 'texi2dvi' program takes care of all the steps for producing a TeX DVI file from a Texinfo document. Similarly, 'texi2pdf' produces a PDF file. To run 'texi2dvi' or 'texi2pdf' on an input file 'foo.texi', do this (where 'prompt$ ' is your shell prompt): prompt$ texi2dvi foo.texi prompt$ texi2pdf foo.texi As shown in this example, the input filenames to 'texi2dvi' and 'texi2pdf' must include any extension, such as '.texi'. (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::). 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 provided as a convenience for AUC-TeX (*note (auctex)Top::, as it prefers to merely prepend 'pdf' to DVI producing tools to have PDF producing tools. With the '--dvipdf' option, 'texi2dvi' produces PDF output by running TeX and then a DVI-to-PDF program: if the 'DVIPDF' environment variable is set, that value is used, else the first program extant among 'dvipdfmx', 'dvipdfm', 'dvipdf', 'dvi2pdf', 'dvitopdf'. This method generally supports CJK typesetting better than 'pdftex'. With the '--ps' option, 'texi2dvi' produces PostScript instead of DVI, by running 'tex' and then 'dvips' (*note (dvips)Top::). (Or the value of the 'DVIPS' environment variable, if set.) 'texi2dvi' can also be used to process LaTeX files. Normally 'texi2dvi' is able to guess the input file language by its contents and file name extension; however, if it guesses wrong you can explicitly 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; this extended version of TeX is not required, and the DVI output is identical, but it runs faster in some cases, and provide additional tracing information when debugging 'texinfo.tex'. (These days, 'pdftex' and 'pdfetex' are exactly the same, but we still run 'pdfetex' to cater to ancient TeX installations.) The option '-E' (equivalently, '-e' and '--expand') does Texinfo macro expansion using 'makeinfo' instead of the TeX implementation (*note Macro Details::). Each implementation has its own limitations and advantages. If this option is used, the string '@c _texi2dvi' must not appear at the beginning of a line in the source file. For a list of all the options, run 'texi2dvi --help'.  File: texinfo.info, Node: Format with tex/texindex, Next: Print with lpr, Prev: Format with texi2dvi, Up: Hardcopy 21.3 Format with 'tex'/'texindex' ================================= You can do the basic formatting of a 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, perhaps after a further conversion (see the previous section). 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. ('texi2dvi', described in the previous section, runs 'tex' and 'texindex' as necessary.) 'tex' outputs unsorted index files under names following a standard convention: the name of your main input file with any '.texi' or similar extension replaced by the two letter index name. For example, the raw index output files for the input file 'foo.texi' would be, by default, '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, it's typical to 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 two letter indices that you have defined yourself using '@defindex' or '@defcodeindex'. You can safely run 'texindex foo.??' even if there are 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; for example, 'foo.cps' is made from 'foo.cp'. The '@printindex' command looks for a file with that name (*note Printing Indices & Menus::). TeX does not read the raw index output file, and 'texindex' does not alter it. After you have sorted the indices, you need to rerun 'tex' on the Texinfo file. This regenerates the output 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. (Alternatively, it's a one-step process: run 'texi2dvi'; see the previous section.) 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 the previous run, 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. * Menu: * Formatting Partial Documents:: * Details of texindex::  File: texinfo.info, Node: Formatting Partial Documents, Next: Details of texindex, Up: Format with tex/texindex 21.3.1 Formatting Partial Documents ----------------------------------- Sometimes you may wish to print a document while you know it is incomplete, or to print just one chapter of a document. In such a case, the usual auxiliary files that TeX creates and warnings TeX gives about undefined cross references are just nuisances. You can avoid them with the '@novalidate' command, which you must give _before_ the '@setfilename' command (*note @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::). Furthermore, you need not run 'texindex' each time after you run 'tex'. The 'tex' formatting command simply uses whatever sorted index files happen to exist from a previous use of 'texindex'. If those are out of date, that is usually ok while you are creating or debugging a document.  File: texinfo.info, Node: Details of texindex, Prev: Formatting Partial Documents, Up: Format with tex/texindex 21.3.2 Details of texindex -------------------------- In Texinfo version 6, released in 2015, the 'texindex' program was completely reimplemented. The principal functional difference is that index entries beginning with a left brace or right brace ('{' resp. '}') can work properly. For example, these simple index entries are processed correctly, including the "index initial" shown in the index: @cindex @{ @cindex @} ... @printindex cp However, to enable this behavior, it's necessary (for the time being) to give a special option to TeX early in a source document: @tex \global\usebracesinindexestrue @end tex This is because the previous 'texindex' implementation aborted with an incorrect error message ('No page number in \entry...') on such index entries when handled in the normal way. Therefore TeX wrote out an incorrect "sort string" using the '|' character; this did not affect the text of the entry, but the index initial was the incorrect '|', and sorting was not perfect. Because of that fatal error, and because relatively few documents have index entries beginning with braces, we want to provide some transition time for installations to have the new 'texindex'. At some point in the future, we'll make '\usebracesinindexes' true by default (the above TeX code will continue to work fine). Although not a matter of functionality, readers may be interested to know that the new 'texindex' is a literate program () using Texinfo for documentation and (portable) 'awk' for code. A single source file, 'texindex/ti.twjr' in this case, produces the runnable program, a printable document, and an online document. The system is called 'texiwebjr' and was created by Arnold Robbins, who also wrote the new 'texindex'. Not coincidentally, he is also the long-time maintainer of Gawk, *note (gawk)Top::). The file 'texindex/Makefile.am' shows example usage of the system.  File: texinfo.info, Node: Print with lpr, Next: Within Emacs, Prev: Format with tex/texindex, Up: Hardcopy 21.4 Print with 'lpr' from Shell ================================ The way to print a DVI file depends on your system installation. Two common ones are 'dvips foo.dvi -o' to make a PostScript file first and then print that, and 'lpr -d foo.dvi' to print a DVI file directly. For example, the following commands will (probably) suffice to sort the indices, format, and print this manual using the 'texi2dvi' shell script (*note Format with texi2dvi::). texi2dvi texinfo.texi dvips texinfo.dvi -o lpr texinfo.ps Depending on the 'lpr' setup on your machine, you might able to combine the last two steps into 'lpr -d texinfo.dvi'. You can also generate a PDF file by running 'texi2pdf' instead of 'texi2dvi'; a PDF is often directly printable. Or you can generate a PCL file by using 'dvilj' instead of 'dvips', if you have a printer that prefers that format. 'lpr' is a standard program on Unix systems, but it is usually absent on MS-DOS/MS-Windows. If so, just create a PostScript or PDF or PCL file, whatever is most convenient, and print that in the usual way for your machine (e.g., by sending to the appropriate port, usually 'PRN').  File: texinfo.info, Node: Within Emacs, Next: Texinfo Mode Printing, Prev: Print with lpr, Up: Hardcopy 21.5 Printing From an Emacs Shell ================================= You can give formatting and printing commands from a shell within GNU Emacs, just like any other shell command. To create a shell within Emacs, type 'M-x shell' (*note (emacs)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. For example, you can use 'texi2dvi' from an Emacs shell. Here is one way to use 'texi2pdf' to format and print 'Using and Porting GNU CC' from a shell within Emacs: texi2pdf gcc.texi lpr gcc.pdf See the next section for more information about formatting and printing in Texinfo mode.  File: texinfo.info, Node: Texinfo Mode Printing, Next: Compile-Command, Prev: Within Emacs, Up: Hardcopy 21.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 (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.info, Node: Compile-Command, Next: Requirements Summary, Prev: Texinfo Mode Printing, Up: Hardcopy 21.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.texi' file, after the '@bye', you could put the following: Local Variables: compile-command: "texi2dvi gdb.texi" End: This technique is most often used by programmers who also compile programs this way; see *note (emacs)Compilation::.  File: texinfo.info, Node: Requirements Summary, Next: Preparing for TeX, Prev: Compile-Command, Up: Hardcopy 21.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, a title page, a copyright page, permissions, and a table of contents. Besides '@bye', the end of a file usually includes indices. (Not to mention that most manuals contain a body of text as well.) For more information, see: * *note @settitle::. * *note @setchapternewpage::. * *note Headings::. * *note Titlepage & Copyright Page::. * *note Printing Indices & Menus::. * *note Contents::.  File: texinfo.info, Node: Preparing for TeX, Next: Overfull hboxes, Prev: Requirements Summary, Up: Hardcopy 21.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 released for general use is available from the usual GNU servers and mirrors: The latest development version is available from the Texinfo source repository: 'texinfo.tex' is essentially a standalone file, and compatibility is of utmost concern; so, if you need or want to try a newer version than came with your system, it nearly always suffices to download it and put it anywhere that TeX will find it (first). You can replace any existing 'texinfo.tex' with a newer version (of course saving the original in case of disaster). 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 use quotation marks other than those used in English, you'll need to have the European Computer Modern fonts (e.g., 'ecrm1000') and (for PDF output) CM-Super fonts (*note Inserting Quotation Marks::). To use the '@euro' command, you'll need the 'feym*' fonts (e.g., 'feymr10'). *Note @euro::. All of the above files (and a whole lot more) should be installed by default in a reasonable TeX installation. Optionally, you may create a file 'texinfo.cnf' for site configuration. This file is read by TeX when the '@setfilename' command is executed (*note @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, 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 '.profile' or '.cshrc' file. Whether you use '.profile' or '.cshrc' depends on whether you use a Bourne shell-compatible ('sh', 'bash', 'ksh', ...) or C shell-compatible ('csh', 'tcsh') command interpreter, respeictvely. In a '.profile' file, you could use the following 'sh' command sequence: TEXINPUTS=.:/home/me/mylib: export TEXINPUTS While in a '.cshrc' file, you could use the following 'csh' command sequence: setenv TEXINPUTS .:/home/me/mylib: On MS-DOS/MS-Windows, you'd do this (note the use of the ';' character as directory separator, instead of ':'): 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.)  File: texinfo.info, Node: Overfull hboxes, Next: @smallbook, Prev: Preparing for TeX, Up: Hardcopy 21.10 Overfull "hboxes" ======================= TeX is sometimes unable to typeset a line within the normal margins. This most often occurs 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 identifier. 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 used 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 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; its default value is '.15\hsize'. '\hsize' is the TeX dimension containing the current line width. For any overfull boxes you do have, 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.info, Node: @smallbook, Next: A4 Paper, Prev: Overfull hboxes, Up: Hardcopy 21.11 '@smallbook': 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::, for other ways to format with '@smallbook' that do not require changing the source file.  File: texinfo.info, Node: A4 Paper, Next: @pagesizes, Prev: @smallbook, Up: Hardcopy 21.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::, 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.info, Node: @pagesizes, Next: Cropmarks and Magnification, Prev: A4 Paper, Up: Hardcopy 21.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 Format with texi2dvi::, and *note Preparing for TeX::, for other ways to specify '@pagesizes' that do not require changing the source file.  File: texinfo.info, Node: Cropmarks and Magnification, Next: PDF Output, Prev: @pagesizes, Up: Hardcopy 21.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 near the beginning of the Texinfo file, before the title page, like this: @cropmarks 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'. The '@cropmarks' command is recognized and ignored in non-TeX output formats. 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 raw 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 \global\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.info, Node: PDF Output, Next: Obtaining TeX, Prev: Cropmarks and Magnification, Up: Hardcopy 21.15 PDF Output ================ The simplest way to generate PDF output from Texinfo source is to run the convenience script 'texi2pdf' (or 'pdftexi2dvi'); this executes the 'texi2dvi' script with the '--pdf' option (*note Format with texi2dvi::). If for some reason you want to process the document by hand, you can 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.gnu.org/software/gv/). (It can also preview PostScript documents.) * 'xpdf', a freely available standalone PDF reader (http://www.foolabs.com/xpdf/) for the X window system. * PDF at Wikipedia (https://en.wikipedia.org/wiki/Portable_Document_Format). At present, Texinfo does not provide '@ifpdf' or '@pdf' commands as for the other output formats, since PDF documents contain many internal low-level offsets and cross-references that would be hard or impossible to specify at the Texinfo source level. PDF files require dedicated 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, notably including all the fonts that are used, so it has its place.  File: texinfo.info, Node: Obtaining TeX, Prev: PDF Output, Up: Hardcopy 21.16 Obtaining TeX =================== TeX is a document formatter that is used by the FSF for its documentation. It is the easiest way to get printed output (e.g., PDF and PostScript) for Texinfo manuals. TeX is freely redistributable, and you can get it over the Internet or on physical media. See .  File: texinfo.info, Node: Generic Translator texi2any, Next: Creating and Installing Info Files, Prev: Hardcopy, Up: Top 22 'texi2any': The Generic Translator for Texinfo ************************************************* 'texi2any' is the generic translator for Texinfo that can produce different output formats and is highly customizable. It supports these formats: Info (by default, or with '--info'), HTML (with '--html'), plain text (with '--plaintext'), Docbook (with '--docbook'), Texinfo XML (with '--xml'). 'makeinfo' is an alias for 'texi2any'. By default, both 'texi2any' and 'makeinfo' generate Info output; indeed, there are no differences in behavior based on the name. Beside these default formats, command line options to 'texi2any' can change many aspects of the output. Beyond that, initialization files provide even more control over the final output--nearly anything not specified in the Texinfo input file. Initialization files are written in Perl, like the main program, and anything which can be specified on the command line can also be specified within a initialization file. The rest of this chapter goes into the details. * Menu: * Reference Implementation:: 'texi2any': the reference implementation. * Invoking texi2any:: Running the translator from a shell. * texi2any Printed Output:: Calling 'texi2dvi'. * Pointer Validation:: How to check that pointers point somewhere. * Customization Variables:: Configuring 'texi2any'. * Internationalization of Document Strings:: Translating program-inserted text. * Invoking pod2texi:: Translating Perl pod to Texinfo. * texi2html:: An ancestor of 'texi2any'.  File: texinfo.info, Node: Reference Implementation, Next: Invoking texi2any, Up: Generic Translator texi2any 22.1 'texi2any': A Texinfo Reference Implementation =================================================== Above, we called 'texi2any' "the" translator for Texinfo instead of just "a" translator, even though (of course) it's technically and legally possible for other implementations to be written. The reason is that alternative implementations are very likely to have subtle, or not-so-subtle, differences in behavior, and thus Texinfo documents would become dependent on the processor. Therefore, it is important to have a reference implementation that defines parts of the language not fully specified by the manual (often intentionally so). It is equally important to have consistent command-line options and other behavior for all processors. For this reason, the once-independent 'texi2html' Perl Texinfo processor was made compatible with the C implementation of 'makeinfo', to avoid continuing with two different implementations (*note History::). The current implementation, 'texi2any', serves as the reference implementation. It inherited the design of customization and other features from 'texi2html' (for more on 'texi2html' compatibility, *note texi2html::). However, 'texi2any' is a full reimplementation: it constructs a tree-based representation of the input document for all back-ends to work from. Extensive tests of the language were developed at the same time as 'texi2any'; we plead with anyone thinking of writing a program to parse Texinfo input to at least make use of these tests. The 'texi2html' wrapper script (*note texi2html::) provides a very simple example of calling 'texi2any' from a shell script; it's in 'util/texi2html' in the Texinfo sources. More consequentially, 'texi-elements-by-size' is an example Perl script using the 'Texinfo::Parser' module interface; it's also in the 'util' source directory. (Its functionality may also be useful to authors; *note texi-elements-by-size::.) With the release of 'texi2any' as the reference implementation, development of both the C implementation of 'makeinfo' and 'texi2html' has been halted. Going forward, we ask authors of Texinfo documents to use only 'texi2any'.  File: texinfo.info, Node: Invoking texi2any, Next: texi2any Printed Output, Prev: Reference Implementation, Up: Generic Translator texi2any 22.2 Invoking 'texi2any'/'makeinfo' from a Shell ================================================ To process a Texinfo file, invoke 'texi2any' or 'makeinfo' (the two names are synonyms for the same program; we'll use the names interchangeably) followed by the name of the Texinfo file. Also select the format you want to output with the appropriate command line option (default is Info). Thus, to create the Info file for Bison, type the following to the shell: texi2any --info bison.texinfo You can specify more than one input file name; each is processed in turn. If an input file name is '-', standard input is read. The 'texi2any' program accept many options. Perhaps the most basic are those that change the output format. By default, 'texi2any' outputs Info. Each command line option is either a long name preceded by '--' or a single 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 lines are filled to only 68 columns: texi2any --fill-column=68 bison.texinfo You can write two or more options in sequence, like this: texi2any --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 (approximately in alphabetical order): '--commands-in-node-names' This option now does nothing, but remains for compatibility. (It used to ensure that @-commands in node names were expanded throughout the document, especially '@value'. This is now done by default.) '--conf-dir=PATH' Prepend PATH to the directory search list for finding customization files that may be loaded with '--init-file' (see below). The PATH value can be a single directory, or a list of several directories separated by the usual path separator character (':' on Unix-like systems, ';' on Windows). '--css-include=FILE' When producing HTML, literally include the contents of FILE, which should contain W3C cascading style sheets specifications, in the '