Mercurial > hg > xemacs-beta

comparison man/texinfo/texinfo.texi @ 5492:e82f5b7010fe

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge some stuff in man, fix up Makefile -------------------- ChangeLog entries follow: -------------------- man/ChangeLog addition: 2010-02-19 Ben Wing <ben@xemacs.org> * widget.texi: * widget.texi (Top): * widget.texi (Introduction): * widget.texi (User Interface): * widget.texi (Programming Example): * widget.texi (Setting Up the Buffer): * widget.texi (Basic Types): * widget.texi (link): * widget.texi (url-link): * widget.texi (info-link): * widget.texi (push-button): * widget.texi (editable-field): * widget.texi (text): * widget.texi (menu-choice): * widget.texi (radio-button-choice): * widget.texi (item): * widget.texi (choice-item): * widget.texi (toggle): * widget.texi (checkbox): * widget.texi (checklist): * widget.texi (editable-list): * widget.texi (group): * widget.texi (Sexp Types): * widget.texi (constants): * widget.texi (generic): * widget.texi (atoms): * widget.texi (composite): * widget.texi (Widget Properties): * widget.texi (Defining New Widgets): * widget.texi (Widget Browser): * widget.texi (Widget Minor Mode): * widget.texi (Utilities): * widget.texi (Widget Wishlist): * widget.texi (Widget Internals): * widget.texi (GNU Free Documentation License): * widget.texi (Index): Sync with FSF 23.1.92. 2010-02-19 Ben Wing <ben@xemacs.org> * texinfo/fdl.texi: New file. * texinfo/texinfo.texi: * texinfo/texinfo.texi (Top): * texinfo/texinfo.texi (Copying Conditions): * texinfo/texinfo.texi (Overview): * texinfo/texinfo.texi (Reporting Bugs): * texinfo/texinfo.texi (Using Texinfo): * texinfo/texinfo.texi (Output Formats): * texinfo/texinfo.texi (Info Files): * texinfo/texinfo.texi (Printed Books): * texinfo/texinfo.texi (Formatting Commands): * texinfo/texinfo.texi (Conventions): * texinfo/texinfo.texi (Comments): * texinfo/texinfo.texi (Minimum): * texinfo/texinfo.texi (Six Parts): * texinfo/texinfo.texi (Short Sample): * texinfo/texinfo.texi (History): * texinfo/texinfo.texi (Texinfo Mode): * texinfo/texinfo.texi (Texinfo Mode Overview): * texinfo/texinfo.texi (XEmacs Editing): * texinfo/texinfo.texi (Inserting): * texinfo/texinfo.texi (Showing the Structure): * texinfo/texinfo.texi (Updating Nodes and Menus): * texinfo/texinfo.texi (Updating Commands): * texinfo/texinfo.texi (Updating Requirements): * texinfo/texinfo.texi (Other Updating Commands): * texinfo/texinfo.texi (Info Formatting): * texinfo/texinfo.texi (Printing): * texinfo/texinfo.texi (Texinfo Mode Summary): * texinfo/texinfo.texi (Beginning a File): * texinfo/texinfo.texi (Sample Beginning): * texinfo/texinfo.texi (Texinfo File Header): * texinfo/texinfo.texi (First Line): * texinfo/texinfo.texi (Start of Header): * texinfo/texinfo.texi (setfilename): * texinfo/texinfo.texi (settitle): * texinfo/texinfo.texi (End of Header): * texinfo/texinfo.texi (Document Permissions): * texinfo/texinfo.texi (copying): * texinfo/texinfo.texi (insertcopying): * texinfo/texinfo.texi (Titlepage & Copyright Page): * texinfo/texinfo.texi (titlepage): * texinfo/texinfo.texi (titlefont center sp): * texinfo/texinfo.texi (title subtitle author): * texinfo/texinfo.texi (Copyright): * texinfo/texinfo.texi (end titlepage): * texinfo/texinfo.texi (headings on off): * texinfo/texinfo.texi (Contents): * texinfo/texinfo.texi (The Top Node): * texinfo/texinfo.texi (Top Node Example): * texinfo/texinfo.texi (Master Menu Parts): * texinfo/texinfo.texi (Global Document Commands): * texinfo/texinfo.texi (documentdescription): * texinfo/texinfo.texi (setchapternewpage): * texinfo/texinfo.texi (paragraphindent): * texinfo/texinfo.texi (firstparagraphindent): * texinfo/texinfo.texi (exampleindent): * texinfo/texinfo.texi (Software Copying Permissions): * texinfo/texinfo.texi (Ending a File): * texinfo/texinfo.texi (Printing Indices & Menus): * texinfo/texinfo.texi (File End): * texinfo/texinfo.texi (Structuring): * texinfo/texinfo.texi (Tree Structuring): * texinfo/texinfo.texi (Structuring Command Types): * texinfo/texinfo.texi (makeinfo top): * texinfo/texinfo.texi (chapter): * texinfo/texinfo.texi (unnumbered & appendix): * texinfo/texinfo.texi (majorheading & chapheading): * texinfo/texinfo.texi (section): * texinfo/texinfo.texi (unnumberedsec appendixsec heading): * texinfo/texinfo.texi (subsection): * texinfo/texinfo.texi (unnumberedsubsec appendixsubsec subheading): * texinfo/texinfo.texi (subsubsection): * texinfo/texinfo.texi (Raise/lower sections): * texinfo/texinfo.texi (Nodes): * texinfo/texinfo.texi (Two Paths): * texinfo/texinfo.texi (Node Menu Illustration): * texinfo/texinfo.texi (node): * texinfo/texinfo.texi (Node Names): * texinfo/texinfo.texi (Writing a Node): * texinfo/texinfo.texi (Node Line Tips): * texinfo/texinfo.texi (Node Line Requirements): * texinfo/texinfo.texi (First Node): * texinfo/texinfo.texi (makeinfo top command): * texinfo/texinfo.texi (makeinfo Pointer Creation): * texinfo/texinfo.texi (anchor): * texinfo/texinfo.texi (Menus): * texinfo/texinfo.texi (Menu Location): * texinfo/texinfo.texi (Writing a Menu): * texinfo/texinfo.texi (Menu Parts): * texinfo/texinfo.texi (Less Cluttered Menu Entry): * texinfo/texinfo.texi (Menu Example): * texinfo/texinfo.texi (Other Info Files): * texinfo/texinfo.texi (Cross References): * texinfo/texinfo.texi (References): * texinfo/texinfo.texi (Cross Reference Commands): * texinfo/texinfo.texi (Cross Reference Parts): * texinfo/texinfo.texi (xref): * texinfo/texinfo.texi (Reference Syntax): * texinfo/texinfo.texi (One Argument): * texinfo/texinfo.texi (Two Arguments): * texinfo/texinfo.texi (Three Arguments): * texinfo/texinfo.texi (Four and Five Arguments): * texinfo/texinfo.texi (Top Node Naming): * texinfo/texinfo.texi (ref): * texinfo/texinfo.texi (pxref): * texinfo/texinfo.texi (inforef): * texinfo/texinfo.texi (uref): * texinfo/texinfo.texi (cite): * texinfo/texinfo.texi (Marking Text): * texinfo/texinfo.texi (Indicating): * texinfo/texinfo.texi (Useful Highlighting): * texinfo/texinfo.texi (code): * texinfo/texinfo.texi (kbd): * texinfo/texinfo.texi (key): * texinfo/texinfo.texi (samp): * texinfo/texinfo.texi (verb): * texinfo/texinfo.texi (var): * texinfo/texinfo.texi (env): * texinfo/texinfo.texi (file): * texinfo/texinfo.texi (command): * texinfo/texinfo.texi (option): * texinfo/texinfo.texi (dfn): * texinfo/texinfo.texi (abbr): * texinfo/texinfo.texi (acronym): * texinfo/texinfo.texi (indicateurl): * texinfo/texinfo.texi (email): * texinfo/texinfo.texi (Emphasis): * texinfo/texinfo.texi (emph & strong): * texinfo/texinfo.texi (Smallcaps): * texinfo/texinfo.texi (Fonts): * texinfo/texinfo.texi (Quotations and Examples): * texinfo/texinfo.texi (Block Enclosing Commands): * texinfo/texinfo.texi (quotation): * texinfo/texinfo.texi (example): * texinfo/texinfo.texi (verbatim): * texinfo/texinfo.texi (verbatiminclude): * texinfo/texinfo.texi (lisp): * texinfo/texinfo.texi (small): * texinfo/texinfo.texi (display): * texinfo/texinfo.texi (format): * texinfo/texinfo.texi (exdent): * texinfo/texinfo.texi (flushleft & flushright): * texinfo/texinfo.texi (noindent): * texinfo/texinfo.texi (indent): * texinfo/texinfo.texi (cartouche): * texinfo/texinfo.texi (Lists and Tables): * texinfo/texinfo.texi (Introducing Lists): * texinfo/texinfo.texi (itemize): * texinfo/texinfo.texi (enumerate): * texinfo/texinfo.texi (Two-column Tables): * texinfo/texinfo.texi (table): * texinfo/texinfo.texi (ftable vtable): * texinfo/texinfo.texi (itemx): * texinfo/texinfo.texi (Multi-column Tables): * texinfo/texinfo.texi (Multitable Column Widths): * texinfo/texinfo.texi (Multitable Rows): * texinfo/texinfo.texi (Special Displays): * texinfo/texinfo.texi (Floats): * texinfo/texinfo.texi (float): * texinfo/texinfo.texi (caption shortcaption): * texinfo/texinfo.texi (listoffloats): * texinfo/texinfo.texi (Images): * texinfo/texinfo.texi (Image Syntax): * texinfo/texinfo.texi (Image Scaling): * texinfo/texinfo.texi (Footnotes): * texinfo/texinfo.texi (Footnote Commands): * texinfo/texinfo.texi (Footnote Styles): * texinfo/texinfo.texi (Indices): * texinfo/texinfo.texi (Index Entries): * texinfo/texinfo.texi (Predefined Indices): * texinfo/texinfo.texi (Indexing Commands): * texinfo/texinfo.texi (Combining Indices): * texinfo/texinfo.texi (syncodeindex): * texinfo/texinfo.texi (synindex): * texinfo/texinfo.texi (New Indices): * texinfo/texinfo.texi (Insertions): * texinfo/texinfo.texi (Atsign Braces Comma): * texinfo/texinfo.texi (Inserting an Atsign): * texinfo/texinfo.texi (Inserting Braces): * texinfo/texinfo.texi (Inserting a Comma): * texinfo/texinfo.texi (Inserting Quote Characters): * texinfo/texinfo.texi (Inserting Space): * texinfo/texinfo.texi (Not Ending a Sentence): * texinfo/texinfo.texi (Ending a Sentence): * texinfo/texinfo.texi (Multiple Spaces): * texinfo/texinfo.texi (frenchspacing): * texinfo/texinfo.texi (dmn): * texinfo/texinfo.texi (Inserting Accents): * texinfo/texinfo.texi (Inserting Quotation Marks): * texinfo/texinfo.texi (Dots Bullets): * texinfo/texinfo.texi (dots): * texinfo/texinfo.texi (bullet): * texinfo/texinfo.texi (TeX and copyright): * texinfo/texinfo.texi (tex): * texinfo/texinfo.texi (copyright symbol): * texinfo/texinfo.texi (registered symbol): * texinfo/texinfo.texi (euro): * texinfo/texinfo.texi (pounds): * texinfo/texinfo.texi (textdegree): * texinfo/texinfo.texi (minus): * texinfo/texinfo.texi (geq leq): * texinfo/texinfo.texi (math): * texinfo/texinfo.texi (Click Sequences): * texinfo/texinfo.texi (Glyphs): * texinfo/texinfo.texi (Glyphs Summary): * texinfo/texinfo.texi (result): * texinfo/texinfo.texi (expansion): * texinfo/texinfo.texi (Print Glyph): * texinfo/texinfo.texi (Error Glyph): * texinfo/texinfo.texi (Equivalence): * texinfo/texinfo.texi (Point Glyph): * texinfo/texinfo.texi (Breaks): * texinfo/texinfo.texi (Break Commands): * texinfo/texinfo.texi (Line Breaks): * texinfo/texinfo.texi (- and hyphenation): * texinfo/texinfo.texi (allowcodebreaks): * texinfo/texinfo.texi (w): * texinfo/texinfo.texi (tie): * texinfo/texinfo.texi (sp): * texinfo/texinfo.texi (page): * texinfo/texinfo.texi (group): * texinfo/texinfo.texi (need): * texinfo/texinfo.texi (Definition Commands): * texinfo/texinfo.texi (Def Cmd Template): * texinfo/texinfo.texi (Def Cmd Continuation Lines): * texinfo/texinfo.texi (Optional Arguments): * texinfo/texinfo.texi (deffnx): * texinfo/texinfo.texi (Def Cmds in Detail): * texinfo/texinfo.texi (Functions Commands): * texinfo/texinfo.texi (Variables Commands): * texinfo/texinfo.texi (Typed Functions): * texinfo/texinfo.texi (Typed Variables): * texinfo/texinfo.texi (Data Types): * texinfo/texinfo.texi (Abstract Objects): * texinfo/texinfo.texi (Object-Oriented Variables): * texinfo/texinfo.texi (Object-Oriented Methods): * texinfo/texinfo.texi (Defining Macros): * texinfo/texinfo.texi (Invoking Macros): * texinfo/texinfo.texi (Macro Details): * texinfo/texinfo.texi (alias): * texinfo/texinfo.texi (definfoenclose): * texinfo/texinfo.texi (Hardcopy): * texinfo/texinfo.texi (Use TeX): * texinfo/texinfo.texi (Format with tex/texindex): * texinfo/texinfo.texi (Format with texi2dvi): * texinfo/texinfo.texi (Print with lpr): * texinfo/texinfo.texi (Within XEmacs): * texinfo/texinfo.texi (Texinfo Mode Printing): * texinfo/texinfo.texi (Compile-Command): * texinfo/texinfo.texi (Requirements Summary): * texinfo/texinfo.texi (Preparing for TeX): * texinfo/texinfo.texi (Overfull hboxes): * texinfo/texinfo.texi (smallbook): * texinfo/texinfo.texi (A4 Paper): * texinfo/texinfo.texi (pagesizes): * texinfo/texinfo.texi (Cropmarks and Magnification): * texinfo/texinfo.texi (PDF Output): * texinfo/texinfo.texi (Obtaining TeX): * texinfo/texinfo.texi (Creating and Installing Info Files): * texinfo/texinfo.texi (Creating an Info File): * texinfo/texinfo.texi (makeinfo advantages): * texinfo/texinfo.texi (Invoking makeinfo): * texinfo/texinfo.texi (makeinfo options): * texinfo/texinfo.texi (Pointer Validation): * texinfo/texinfo.texi (makeinfo in XEmacs): * texinfo/texinfo.texi (texinfo-format commands): * texinfo/texinfo.texi (Batch Formatting): * texinfo/texinfo.texi (Tag and Split Files): * texinfo/texinfo.texi (Installing an Info File): * texinfo/texinfo.texi (Directory File): * texinfo/texinfo.texi (New Info File): * texinfo/texinfo.texi (Other Info Directories): * texinfo/texinfo.texi (Installing Dir Entries): * texinfo/texinfo.texi (Invoking install-info): * texinfo/texinfo.texi (Generating HTML): * texinfo/texinfo.texi (HTML Translation): * texinfo/texinfo.texi (HTML Splitting): * texinfo/texinfo.texi (HTML CSS): * texinfo/texinfo.texi (HTML Xref): * texinfo/texinfo.texi (HTML Xref Link Basics): * texinfo/texinfo.texi (HTML Xref Node Name Expansion): * texinfo/texinfo.texi (HTML Xref Command Expansion): * texinfo/texinfo.texi (HTML Xref 8-bit Character Expansion): * texinfo/texinfo.texi (HTML Xref Mismatch): * texinfo/texinfo.texi (Command List): * texinfo/texinfo.texi (Command Syntax): * texinfo/texinfo.texi (Tips): * texinfo/texinfo.texi (Sample Texinfo Files): * texinfo/texinfo.texi (Short Sample Texinfo File): * texinfo/texinfo.texi (GNU Sample Texts): * texinfo/texinfo.texi (Invoking sample): * texinfo/texinfo.texi (GNU Free Documentation License): * texinfo/texinfo.texi (Index): * texinfo/texinfo.texi (Verbatim Copying License): * texinfo/texinfo.texi (All-permissive Copying License): * texinfo/texinfo.texi (Include Files): * texinfo/texinfo.texi (Using Include Files): * texinfo/texinfo.texi (texinfo-multiple-files-update): * texinfo/texinfo.texi (Include Files Requirements): * texinfo/texinfo.texi (Sample Include File): * texinfo/texinfo.texi (Include Files Evolution): * texinfo/texinfo.texi (Headings): * texinfo/texinfo.texi (Headings Introduced): * texinfo/texinfo.texi (Heading Format): * texinfo/texinfo.texi (Heading Choice): * texinfo/texinfo.texi (Custom Headings): * texinfo/texinfo.texi (Catching Mistakes): * texinfo/texinfo.texi (makeinfo Preferred): * texinfo/texinfo.texi (Debugging with Info): * texinfo/texinfo.texi (Debugging with TeX): * texinfo/texinfo.texi (Using texinfo-show-structure): * texinfo/texinfo.texi (Using occur): * texinfo/texinfo.texi (Running Info-Validate): * texinfo/texinfo.texi (Using Info-validate): * texinfo/texinfo.texi (Unsplit): * texinfo/texinfo.texi (Tagifying): * texinfo/texinfo.texi (Splitting): * texinfo/texinfo.texi (Refilling Paragraphs): * texinfo/texinfo.texi (Command and Variable Index): * texinfo/texinfo.texi (General Index): * texinfo/version.texi: New file. Sync with FSF 23.1.92. Make new directory to hold the files needed to generate texinfo.info, since there are three such files now. 2010-02-19 Ben Wing <ben@xemacs.org> * Makefile: * Makefile (src_files1): * Makefile (DIR): * Makefile (texinfo-srcs): * Makefile ($(INFODIR)/widget.info): * Makefile ($(INFODIR)/texinfo.info): * Makefile (.PHONY): * Makefile (texinfo.dvi): * Makefile (texinfo.pdf): * Makefile ($(HTMLDIR)/widget.html): * Makefile ($(HTMLDIR)/texinfo.html): Incorporate texinfo.texi moving to a subdirectory texinfo/. Do some tricks to reduce the amount of duplication while still maintaining compatible with non-GNU make (at least, with Solaris make). * doclicense.texi: New file. * info.texi: * info.texi (Top): * info.texi (Getting Started): * info.texi (Help-Small-Screen): * info.texi (Help): * info.texi (Help-P): * info.texi (Help-^L): * info.texi (Help-Inv): * info.texi (Help-]): * info.texi (Help-M): * info.texi (Help-FOO): * info.texi (Help-Xref): * info.texi (Help-Int): * info.texi (Help-Q): * info.texi (Advanced): * info.texi (Search Text): * info.texi (Search Index): * info.texi (Go to node): * info.texi (Choose menu subtopic): * info.texi (Create Info buffer): * info.texi (XEmacs Info Variables): * info.texi (Expert Info): * info.texi (Add): * info.texi (Menus): * info.texi (Cross-refs): * info.texi (Help-Cross): * info.texi (Tags): * info.texi (Checking): * info.texi (Index): * texinfo.tex: * texinfo.tex (paragraphindent{%): * texinfo.tex (sectionheading will have): * texinfo.tex (chapterzzz{#3}%): * texinfo.tex (subsubsection = \numberedsubsubsec): * texinfo.tex (subsubsection = \appendixsubsubsec): * texinfo.tex (subsubsection = \unnumberedsubsubsec): * texinfo.tex (sectionheading{#1}{sec}{Ynumbered}{\the\chapno.\the\secno}%): * texinfo.tex (sectionheading{#1}{sec}{Yappendix}{\appendixletter.\the\secno}%): * texinfo.tex (sectionheading{#1}{sec}{Ynothing}{\the\unnumberedno.\the\secno}%): * texinfo.tex (sectionheading{#1}{subsec}{Ynumbered}{\the\chapno.\the\secno.\the\subsecno}%): * texinfo.tex (sectionheading{#1}{subsec}{Yappendix}%): * texinfo.tex (sectionheading{#1}{subsec}{Ynothing}%): * texinfo.tex (sectionheading{#1}{subsubsec}{Ynumbered}%): * texinfo.tex (sectionheading{#1}{subsubsec}{Yappendix}%): * texinfo.tex (sectionheading{#1}{subsubsec}{Ynothing}%): * texinfo.tex (sectionheading{#1}{subsubsec}{Yomitfromtoc}{}): * texinfo.tex (sectionheading to do the printing.): * texinfo.tex (sectionlevel}{#1}{#4}%): * texinfo.tex (sectionheading, q.v.): Sync with FSF 23.1.92.
author Ben Wing <ben@xemacs.org>
date Fri, 19 Feb 2010 22:39:19 -0600
parents man/texinfo.texi@1094d6d400fb
children
comparison
equal deleted inserted replaced
5491:06dd936cde16 5492:e82f5b7010fe
1 \input texinfo.tex @c -*-texinfo-*-
2 @c $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
3 @c Ordinarily, Texinfo files have the extension .texi. But texinfo.texi
4 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
5
6 @c Everything between the start/end of header lines will be passed by
7 @c XEmacs's {texinfo,makeinfo}-format region commands. See the `start of
8 @c header' node for more info.
9 @c %**start of header
10 @c Synced up with: Texinfo 4.13 of Sep 18, 2008.
11 @c Synced by: Ben Wing, 2-17-10.
12
13 @c makeinfo and texinfo.tex ignore all text before @setfilename.
14 @c
15 @c Ordinarily, the setfilename argument ends with .info. But
16 @c texinfo.info-13 is too long for 14-character filesystems.
17 @setfilename ../../info/texinfo.info
18
19 @c Automake automatically updates version.texi to @set VERSION and
20 @c @set UPDATED to appropriate values.
21 @include version.texi
22 @c XEmacs: @settitle Texinfo @value{edition}
23 @settitle GNU Texinfo @value{VERSION}
24
25 @c Define a new index for options.
26 @defcodeindex op
27 @c Put everything except function (command, in this case) names in one
28 @c index (arbitrarily chosen to be the concept index).
29 @syncodeindex op cp
30 @syncodeindex vr cp
31 @syncodeindex pg cp
32
33 @paragraphindent 2
34 @c finalout
35
36 @comment %**end of header
37
38 @copying
39 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
40 a documentation system that can produce both online information and a
41 printed manual from a single source.
42
43 Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 1996, 1997,
44 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
45 Free Software Foundation, Inc.
46
47 @quotation
48 Permission is granted to copy, distribute and/or modify this document
49 under the terms of the GNU Free Documentation License, Version 1.2 or
50 any later version published by the Free Software Foundation; with no
51 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'',
52 and with the Back-Cover Texts as in (a) below. A copy of the license
53 is included in the section entitled ``GNU Free Documentation
54 License.''
55
56 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
57 this GNU Manual. Buying copies from GNU Press supports the FSF in
58 developing GNU and promoting software freedom.''
59 @end quotation
60 @end copying
61
62 @dircategory Texinfo documentation system
63 @direntry
64 * Texinfo: (texinfo). The GNU documentation format.
65 * install-info: (texinfo)Invoking install-info. Update info/dir entries.
66 * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents.
67 * texi2pdf: (texinfo)PDF Output. PDF output for Texinfo.
68 * pdftexi2dvi: (texinfo)PDF Output. PDF output for Texinfo.
69 * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files.
70 * makeinfo: (texinfo)Invoking makeinfo. Translate Texinfo source.
71 @end direntry
72
73 @c Before release, run C-u C-c C-u C-a (texinfo-all-menus-update with a
74 @c prefix arg). This updates the node pointers, which texinfmt.el needs.
75
76 @c Set smallbook if printing in smallbook format so the example of the
77 @c smallbook font is actually written using smallbook; in bigbook, a kludge
78 @c is used for TeX output. Do this through the -t option to texi2dvi,
79 @c so this same source can be used for other paper sizes as well.
80 @c smallbook
81 @c set smallbook
82 @c @@clear smallbook
83
84 @c If you like blank pages, add through texi2dvi -t.
85 @c setchapternewpage odd
86
87 @c Currently undocumented command, 5 December 1993:
88 @c nwnode (Same as node, but no warnings; for `makeinfo'.)
89
90
91 @shorttitlepage GNU Texinfo
92
93 @titlepage
94 @title Texinfo
95 @subtitle The GNU Documentation Format
96 @subtitle for Texinfo version @value{VERSION}, @value{UPDATED}
97
98 @author Robert J. Chassell
99 @author Richard M. Stallman
100
101 @c Include the Distribution inside the titlepage so
102 @c that headings are turned off.
103
104 @page
105 @vskip 0pt plus 1filll
106 @insertcopying
107
108 @sp 1
109 Published by the Free Software Foundation @*
110 51 Franklin St, Fifth Floor @*
111 Boston, MA 02110-1301 @*
112 USA @*
113 ISBN 1-882114-67-1 @c for version 4.0, September 1999.
114 @c ISBN 1-882114-65-5 is for version 3.12, March 1998.
115 @c ISBN 1-882114-64-7 is for edition 2.24 of November 1996.
116 @c ISBN 1-882114-63-9 is for edition 2.20 of 28 February 1995.
117
118 @sp 1
119 Cover art by Etienne Suvasa.
120 @end titlepage
121
122
123 @summarycontents
124 @contents
125
126
127 @ifnottex
128 @node Top
129 @top Texinfo
130
131 This manual is for GNU Texinfo (version @value{VERSION}, @value{UPDATED}),
132 a documentation system that can produce both online information and a
133 printed manual from a single source.
134
135 The first part of this master menu lists the major nodes in this Info
136 document, including the @@-command and concept indices. The rest of
137 the menu lists all the lower level nodes in the document.
138
139 @end ifnottex
140
141 @menu
142 * Copying Conditions:: Your rights.
143 * Overview:: Texinfo in brief.
144 * Texinfo Mode:: Using the XEmacs Texinfo mode.
145 * Beginning a File:: What is at the beginning of a Texinfo file?
146 * Ending a File:: What is at the end of a Texinfo file?
147 * Structuring:: Creating chapters, sections, appendices, etc.
148 * Nodes:: Writing nodes, the basic unit of Texinfo.
149 * Menus:: Writing menus.
150 * Cross References:: Writing cross references.
151 * Marking Text:: Marking words and phrases as code,
152 keyboard input, meta-syntactic
153 variables, and the like.
154 * Quotations and Examples:: Block quotations, examples, etc.
155 * Lists and Tables:: Itemized or numbered lists, and tables.
156 * Special Displays:: Floating figures and footnotes.
157 * Indices:: Creating indices.
158 * Insertions:: Inserting @@-signs, braces, etc.
159 * Breaks:: Forcing or preventing line and page breaks.
160 * Definition Commands:: Describing functions and the like uniformly.
161 * Conditionals:: Specifying text for only some output cases.
162 * Internationalization:: Supporting languages other than English.
163 * Defining New Texinfo Commands:: User-defined macros and aliases.
164 * Hardcopy:: Output for paper, with @TeX{}.
165 * Creating and Installing Info Files:: Details on Info output.
166 * Generating HTML:: Details on HTML output.
167
168 * Command List:: All the Texinfo @@-commands.
169 * Tips:: Hints on how to write a Texinfo document.
170 * Sample Texinfo Files:: Complete examples, including full texts.
171 * Include Files:: How to incorporate other Texinfo files.
172 * Headings:: How to write page headings and footings.
173 * Catching Mistakes:: How to find formatting mistakes.
174 * GNU Free Documentation License::Copying this manual.
175 * Command and Variable Index:: A menu containing commands and variables.
176 * General Index:: A menu covering many topics.
177
178 @detailmenu
179 --- The Detailed Node Listing ---
180
181 Overview of Texinfo
182
183 * Reporting Bugs:: Submitting effective bug reports.
184 * Using Texinfo:: Create printed or online output.
185 * Output Formats:: Overview of the supported output formats.
186 * Info Files:: What is an Info file?
187 * Printed Books:: Characteristics of a printed book or manual.
188 * Formatting Commands:: @@-commands are used for formatting.
189 * Conventions:: General rules for writing a Texinfo file.
190 * Comments:: Writing comments and ignored text in general.
191 * Minimum:: What a Texinfo file must have.
192 * Six Parts:: Usually, a Texinfo file has six parts.
193 * Short Sample:: A short sample Texinfo file.
194 * History:: Acknowledgements, contributors and genesis.
195
196 Using Texinfo Mode
197
198 * Texinfo Mode Overview:: How Texinfo mode can help you.
199 * XEmacs Editing:: Texinfo mode adds to XEmacs' general
200 purpose editing features.
201 * Inserting:: How to insert frequently used @@-commands.
202 * Showing the Structure:: How to show the structure of a file.
203 * Updating Nodes and Menus:: How to update or create new nodes and menus.
204 * Info Formatting:: How to format for Info.
205 * Printing:: How to format and print part or all of a file.
206 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
207
208 Updating Nodes and Menus
209
210 * Updating Commands:: Five major updating commands.
211 * Updating Requirements:: How to structure a Texinfo file for
212 using the updating command.
213 * Other Updating Commands:: How to indent descriptions, insert
214 missing nodes lines, and update
215 nodes in sequence.
216
217 Beginning a Texinfo File
218
219 * Sample Beginning:: A sample beginning for a Texinfo file.
220 * Texinfo File Header:: The first lines.
221 * Document Permissions:: Ensuring your manual is free.
222 * Titlepage & Copyright Page:: Creating the title and copyright pages.
223 * Contents:: How to create a table of contents.
224 * The Top Node:: Creating the `Top' node and master menu.
225 * Global Document Commands:: Affecting formatting throughout.
226 * Software Copying Permissions:: Ensure that you and others continue to
227 have the right to use and share software.
228
229 Texinfo File Header
230
231 * First Line:: The first line of a Texinfo file.
232 * Start of Header:: Formatting a region requires this.
233 * setfilename:: Tell Info the name of the Info file.
234 * settitle:: Create a title for the printed work.
235 * End of Header:: Formatting a region requires this.
236
237 Document Permissions
238
239 * copying:: Declare the document's copying permissions.
240 * insertcopying:: Where to insert the permissions.
241
242 Title and Copyright Pages
243
244 * titlepage:: Create a title for the printed document.
245 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
246 and @code{@@sp} commands.
247 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
248 and @code{@@author} commands.
249 * Copyright:: How to write the copyright notice and
250 include copying permissions.
251 * end titlepage:: Turn on page headings after the title and
252 copyright pages.
253 * headings on off:: An option for turning headings on and off
254 and double or single sided printing.
255
256 The `Top' Node and Master Menu
257
258 * Top Node Example::
259 * Master Menu Parts::
260
261 Global Document Commands
262
263 * documentdescription:: Document summary for the HTML output.
264 * setchapternewpage:: Start chapters on right-hand pages.
265 * paragraphindent:: Specify paragraph indentation.
266 * firstparagraphindent:: Suppress indentation of the first paragraph.
267 * exampleindent:: Specify environment indentation.
268
269 Ending a Texinfo File
270
271 * Printing Indices & Menus:: How to print an index in hardcopy and
272 generate index menus in Info.
273 * File End:: How to mark the end of a file.
274
275 Chapter Structuring
276
277 * Tree Structuring:: A manual is like an upside down tree @dots{}
278 * Structuring Command Types:: How to divide a manual into parts.
279 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
280 * chapter::
281 * unnumbered & appendix::
282 * majorheading & chapheading::
283 * section::
284 * unnumberedsec appendixsec heading::
285 * subsection::
286 * unnumberedsubsec appendixsubsec subheading::
287 * subsubsection:: Commands for the lowest level sections.
288 * Raise/lower sections:: How to change commands' hierarchical level.
289
290 Nodes
291
292 * Two Paths:: Different commands to structure
293 Info output and printed output.
294 * Node Menu Illustration:: A diagram, and sample nodes and menus.
295 * node:: Creating nodes, in detail.
296 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
297 * anchor:: Defining arbitrary cross-reference targets.
298
299 The @code{@@node} Command
300
301 * Node Names:: How to choose node and pointer names.
302 * Writing a Node:: How to write an @code{@@node} line.
303 * Node Line Tips:: Keep names short.
304 * Node Line Requirements:: Keep names unique, without @@-commands.
305 * First Node:: How to write a `Top' node.
306 * makeinfo top command:: How to use the @code{@@top} command.
307
308 Menus
309
310 * Menu Location:: Menus go at the ends of short nodes.
311 * Writing a Menu:: What is a menu?
312 * Menu Parts:: A menu entry has three parts.
313 * Less Cluttered Menu Entry:: Two part menu entry.
314 * Menu Example:: Two and three part menu entries.
315 * Other Info Files:: How to refer to a different Info file.
316
317 Cross References
318
319 * References:: What cross references are for.
320 * Cross Reference Commands:: A summary of the different commands.
321 * Cross Reference Parts:: A cross reference has several parts.
322 * xref:: Begin a reference with `See' @dots{}
323 * Top Node Naming:: How to refer to the beginning of another file.
324 * ref:: A reference for the last part of a sentence.
325 * pxref:: How to write a parenthetical cross reference.
326 * inforef:: How to refer to an Info-only file.
327 * uref:: How to refer to a uniform resource locator.
328 * cite:: How to refer to books not in the Info system.
329
330 @code{@@xref}
331
332 * Reference Syntax:: What a reference looks like and requires.
333 * One Argument:: @code{@@xref} with one argument.
334 * Two Arguments:: @code{@@xref} with two arguments.
335 * Three Arguments:: @code{@@xref} with three arguments.
336 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
337
338 Marking Words and Phrases
339
340 * Indicating:: How to indicate definitions, files, etc.
341 * Emphasis:: How to emphasize text.
342
343 Indicating Definitions, Commands, etc.
344
345 * Useful Highlighting:: Highlighting provides useful information.
346 * code:: Indicating program code.
347 * kbd:: Showing keyboard input.
348 * key:: Specifying keys.
349 * samp:: A literal sequence of characters.
350 * verb:: A verbatim sequence of characters.
351 * var:: Indicating metasyntactic variables.
352 * env:: Indicating environment variables.
353 * file:: Indicating file names.
354 * command:: Indicating command names.
355 * option:: Indicating option names.
356 * dfn:: Specifying definitions.
357 * abbr:: Indicating abbreviations.
358 * acronym:: Indicating acronyms.
359 * indicateurl:: Indicating a World Wide Web reference.
360 * email:: Indicating an electronic mail address.
361
362 Emphasizing Text
363
364 * emph & strong:: How to emphasize text in Texinfo.
365 * Smallcaps:: How to use the small caps font.
366 * Fonts:: Various font commands for printed output.
367
368 Quotations and Examples
369
370 * Block Enclosing Commands:: Different constructs for different purposes.
371 * quotation:: Writing a quotation.
372 * example:: Writing an example in a fixed-width font.
373 * verbatim:: Writing a verbatim example.
374 * verbatiminclude:: Including a file verbatim.
375 * lisp:: Illustrating Lisp code.
376 * small:: Examples in a smaller font.
377 * display:: Writing an example in the current font.
378 * format:: Writing an example without narrowed margins.
379 * exdent:: Undo indentation on a line.
380 * flushleft & flushright:: Pushing text flush left or flush right.
381 * noindent:: Preventing paragraph indentation.
382 * indent:: Forcing paragraph indentation.
383 * cartouche:: Drawing rounded rectangles around examples.
384
385 Lists and Tables
386
387 * Introducing Lists:: Texinfo formats lists for you.
388 * itemize:: How to construct a simple list.
389 * enumerate:: How to construct a numbered list.
390 * Two-column Tables:: How to construct a two-column table.
391 * Multi-column Tables:: How to construct generalized tables.
392
393 Making a Two-column Table
394
395 * table:: How to construct a two-column table.
396 * ftable vtable:: Automatic indexing for two-column tables.
397 * itemx:: How to put more entries in the first column.
398
399 @code{@@multitable}: Multi-column Tables
400
401 * Multitable Column Widths:: Defining multitable column widths.
402 * Multitable Rows:: Defining multitable rows, with examples.
403
404 Special Displays
405
406 * Floats:: Figures, tables, and the like.
407 * Images:: Including graphics and images.
408 * Footnotes:: Writing footnotes.
409
410 Floats
411
412 * float:: Producing floating material.
413 * caption shortcaption:: Specifying descriptions for floats.
414 * listoffloats:: A table of contents for floats.
415
416 Inserting Images
417
418 * Image Syntax::
419 * Image Scaling::
420
421 Footnotes
422
423 * Footnote Commands:: How to write a footnote in Texinfo.
424 * Footnote Styles:: Controlling how footnotes appear in Info.
425
426 Indices
427
428 * Index Entries:: Choose different words for index entries.
429 * Predefined Indices:: Use different indices for different kinds
430 of entries.
431 * Indexing Commands:: How to make an index entry.
432 * Combining Indices:: How to combine indices.
433 * New Indices:: How to define your own indices.
434
435 Combining Indices
436
437 * syncodeindex:: How to merge two indices, using @code{@@code}
438 font for the merged-from index.
439 * synindex:: How to merge two indices, using the
440 default font of the merged-to index.
441
442 Special Insertions
443
444 * Atsign Braces Comma:: Inserting @@ and @{@} and ,.
445 * Inserting Quote Characters:: Inserting left and right quotes, in code.
446 * Inserting Space:: How to insert the right amount of space
447 within a sentence.
448 * Inserting Accents:: How to insert accents and special characters.
449 * Inserting Quotation Marks:: How to insert quotation marks.
450 * Dots Bullets:: How to insert dots and bullets.
451 * TeX and copyright:: How to insert the @TeX{} logo
452 and the copyright symbol.
453 * euro:: How to insert the Euro currency symbol.
454 * pounds:: How to insert the pounds currency symbol.
455 * textdegree:: How to insert the degrees symbol.
456 * minus:: How to insert a minus sign.
457 * geq leq:: How to insert greater/less-than-or-equal signs.
458 * math:: How to format a mathematical expression.
459 * Click Sequences:: Inserting GUI usage sequences.
460 * Glyphs:: How to indicate results of evaluation,
461 expansion of macros, errors, etc.
462
463 Inserting @@ and @{@} and @comma{}
464
465 * Inserting an Atsign::
466 * Inserting Braces::
467 * Inserting a Comma::
468
469 Inserting Space
470
471 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
472 * Ending a Sentence:: Sometimes it does.
473 * Multiple Spaces:: Inserting multiple spaces.
474 * frenchspacing:: Specifying end-of-sentence spacing.
475 * dmn:: How to format a dimension.
476
477 Inserting Ellipsis and Bullets
478
479 * dots:: How to insert dots @dots{}
480 * bullet:: How to insert a bullet.
481
482 Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{}
483
484 * tex:: The @TeX{} logos.
485 * copyright symbol:: The copyright symbol (c in a circle).
486 * registered symbol:: The registered symbol (R in a circle).
487
488 Glyphs for Examples
489
490 * Glyphs Summary::
491 * result:: How to show the result of expression.
492 * expansion:: How to indicate an expansion.
493 * Print Glyph:: How to indicate printed output.
494 * Error Glyph:: How to indicate an error message.
495 * Equivalence:: How to indicate equivalence.
496 * Point Glyph:: How to indicate the location of point.
497
498 Glyphs Summary
499
500 * result::
501 * expansion::
502 * Print Glyph::
503 * Error Glyph::
504 * Equivalence::
505 * Point Glyph::
506
507 Forcing and Preventing Breaks
508
509 * Break Commands:: Summary of break-related commands.
510 * Line Breaks:: Forcing line breaks.
511 * - and hyphenation:: Helping @TeX{} with hyphenation points.
512 * allowcodebreaks:: Controlling line breaks within @@code text.
513 * w:: Preventing unwanted line breaks in text.
514 * tie:: Inserting an unbreakable but varying space.
515 * sp:: Inserting blank lines.
516 * page:: Forcing the start of a new page.
517 * group:: Preventing unwanted page breaks.
518 * need:: Another way to prevent unwanted page breaks.
519
520 Definition Commands
521
522 * Def Cmd Template:: Writing descriptions using definition commands.
523 * Def Cmd Continuation Lines:: Continuing the heading over source lines.
524 * Optional Arguments:: Handling optional and repeated arguments.
525 * deffnx:: Group two or more `first' lines.
526 * Def Cmds in Detail:: Reference for all the definition commands.
527 * Def Cmd Conventions:: Conventions for writing definitions.
528 * Sample Function Definition:: An example.
529
530 The Definition Commands
531
532 * Functions Commands:: Commands for functions and similar entities.
533 * Variables Commands:: Commands for variables and similar entities.
534 * Typed Functions:: Commands for functions in typed languages.
535 * Typed Variables:: Commands for variables in typed languages.
536 * Data Types:: The definition command for data types.
537 * Abstract Objects:: Commands for object-oriented programming.
538
539 Object-Oriented Programming
540
541 * Variables: Object-Oriented Variables.
542 * Methods: Object-Oriented Methods.
543
544 Conditionally Visible Text
545
546 * Conditional Commands:: Text for a given format.
547 * Conditional Not Commands:: Text for any format other than a given one.
548 * Raw Formatter Commands:: Using raw formatter commands.
549 * set clear value:: Variable tests and substitutions.
550 * Conditional Nesting:: Using conditionals inside conditionals.
551
552 @code{@@set}, @code{@@clear}, and @code{@@value}
553
554 * set value:: Expand a flag variable to a string.
555 * ifset ifclear:: Format a region if a flag is set.
556 * value Example:: An easy way to update edition information.
557
558 Internationalization
559
560 * documentlanguage:: Declaring the current language.
561 * documentencoding:: Declaring the input encoding.
562
563 Defining New Texinfo Commands
564
565 * Defining Macros:: Defining and undefining new commands.
566 * Invoking Macros:: Using a macro, once you've defined it.
567 * Macro Details:: Limitations of Texinfo macros.
568 * alias:: Command aliases.
569 * definfoenclose:: Customized highlighting.
570
571 Formatting and Printing Hardcopy
572
573 * Use TeX:: Use @TeX{} to format for hardcopy.
574 * Format with tex/texindex:: How to format with explicit shell commands.
575 * Format with texi2dvi:: A simpler way to format.
576 * Print with lpr:: How to print.
577 * Within XEmacs:: How to format and print from an XEmacs shell.
578 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
579 * Compile-Command:: How to print using XEmacs's compile command.
580 * Requirements Summary:: @TeX{} formatting requirements summary.
581 * Preparing for TeX:: What to do before you use @TeX{}.
582 * Overfull hboxes:: What are and what to do with overfull hboxes.
583 * smallbook:: How to print small format books and manuals.
584 * A4 Paper:: How to print on A4 or A5 paper.
585 * pagesizes:: How to print with customized page sizes.
586 * Cropmarks and Magnification:: How to print marks to indicate the size
587 of pages and how to print scaled up output.
588 * PDF Output:: Portable Document Format output.
589 * Obtaining TeX:: How to Obtain @TeX{}.
590
591 Creating and Installing Info Files
592
593 * Creating an Info File::
594 * Installing an Info File::
595
596 Creating an Info File
597
598 * makeinfo advantages:: @code{makeinfo} provides better error checking.
599 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
600 * makeinfo options:: Specify fill-column and other options.
601 * Pointer Validation:: How to check that pointers point somewhere.
602 * makeinfo in XEmacs:: How to run @code{makeinfo} from XEmacs.
603 * texinfo-format commands:: Two Info formatting commands written
604 in XEmacs Lisp are an alternative
605 to @code{makeinfo}.
606 * Batch Formatting:: How to format for Info in XEmacs Batch mode.
607 * Tag and Split Files:: How tagged and split files help Info
608 to run better.
609
610 Installing an Info File
611
612 * Directory File:: The top level menu for all Info files.
613 * New Info File:: Listing a new Info file.
614 * Other Info Directories:: How to specify Info files that are
615 located in other directories.
616 * Installing Dir Entries:: How to specify what menu entry to add
617 to the Info directory.
618 * Invoking install-info:: @code{install-info} options.
619
620 Generating HTML
621
622 * HTML Translation:: Details of the HTML output.
623 * HTML Splitting:: How HTML output is split.
624 * HTML CSS:: Influencing HTML output with Cascading Style Sheets.
625 * HTML Xref:: Cross-references in HTML output.
626
627 HTML Cross-references
628
629 * Link Basics: HTML Xref Link Basics.
630 * Node Expansion: HTML Xref Node Name Expansion.
631 * Command Expansion: HTML Xref Command Expansion.
632 * 8-bit Expansion: HTML Xref 8-bit Character Expansion.
633 * Mismatch: HTML Xref Mismatch.
634
635 @@-Command List
636
637 * Command Syntax:: General syntax for varieties of @@-commands.
638
639 Sample Texinfo Files
640
641 * Short Sample Texinfo File::
642 * GNU Sample Texts::
643 * Verbatim Copying License::
644 * All-permissive Copying License::
645
646 GNU Free Documentation License
647
648 Include Files
649
650 * Using Include Files:: How to use the @code{@@include} command.
651 * texinfo-multiple-files-update:: How to create and update nodes and
652 menus when using included files.
653 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
654 * Sample Include File:: A sample outer file with included files
655 within it; and a sample included file.
656 * Include Files Evolution:: How use of the @code{@@include} command
657 has changed over time.
658
659 Page Headings
660
661 * Headings Introduced:: Conventions for using page headings.
662 * Heading Format:: Standard page heading formats.
663 * Heading Choice:: How to specify the type of page heading.
664 * Custom Headings:: How to create your own headings and footings.
665
666 Formatting Mistakes
667
668 * makeinfo Preferred:: @code{makeinfo} finds errors.
669 * Debugging with Info:: How to catch errors with Info formatting.
670 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
671 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
672 * Using occur:: How to list all lines containing a pattern.
673 * Running Info-Validate:: How to find badly referenced nodes.
674
675 Finding Badly Referenced Nodes
676
677 * Using Info-validate:: How to run @code{Info-validate}.
678 * Unsplit:: How to create an unsplit file.
679 * Tagifying:: How to tagify a file.
680 * Splitting:: How to split a file manually.
681
682 @end detailmenu
683 @end menu
684
685 @c Reward readers for getting to the end of the menu :).
686 @c Contributed by Arnold Robbins.
687 @quotation
688 Documentation is like sex: when it is good, it is very, very good; and
689 when it is bad, it is better than nothing.
690 ---Dick Brandon
691 @end quotation
692
693
694 @node Copying Conditions
695 @unnumbered Texinfo Copying Conditions
696 @cindex Copying conditions
697 @cindex Conditions for copying Texinfo
698
699 The programs currently being distributed that relate to Texinfo include
700 @code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}.
701 These programs are @dfn{free}; this means that everyone is free to use
702 them and free to redistribute them on a free basis. The Texinfo-related
703 programs are not in the public domain; they are copyrighted and there
704 are restrictions on their distribution, but these restrictions are
705 designed to permit everything that a good cooperating citizen would want
706 to do. What is not allowed is to try to prevent others from further
707 sharing any version of these programs that they might get from you.
708
709 Specifically, we want to make sure that you have the right to give away
710 copies of the programs that relate to Texinfo, that you receive source
711 code or else can get it if you want it, that you can change these
712 programs or use pieces of them in new free programs, and that you know
713 you can do these things.
714
715 To make sure that everyone has such rights, we have to forbid you to
716 deprive anyone else of these rights. For example, if you distribute
717 copies of the Texinfo related programs, you must give the recipients all
718 the rights that you have. You must make sure that they, too, receive or
719 can get the source code. And you must tell them their rights.
720
721 Also, for our own protection, we must make certain that everyone finds
722 out that there is no warranty for the programs that relate to Texinfo.
723 If these programs are modified by someone else and passed on, we want
724 their recipients to know that what they have is not what we distributed,
725 so that any problems introduced by others will not reflect on our
726 reputation.
727
728 The precise conditions of the licenses for the programs currently being
729 distributed that relate to Texinfo are found in the General Public
730 Licenses that accompany them. This manual specifically is covered by
731 the GNU Free Documentation License (@pxref{GNU Free Documentation
732 License}).
733
734
735 @node Overview
736 @chapter Overview of Texinfo
737 @cindex Overview of Texinfo
738 @cindex Texinfo overview
739
740 @dfn{Texinfo}@footnote{The first syllable of ``Texinfo'' is pronounced
741 like ``speck'', not ``hex''. This odd pronunciation is derived from,
742 but is not the same as, the pronunciation of @TeX{}. In the word
743 @TeX{}, the @samp{X} is actually the Greek letter ``chi'' rather than
744 the English letter ``ex''. Pronounce @TeX{} as if the @samp{X} were the
745 last sound in the name `Bach'; but pronounce Texinfo as if the @samp{x}
746 were a `k'. Spell ``Texinfo'' with a capital ``T'' and the other
747 letters in lower case.} is a documentation system that uses a single
748 source file to produce both online information and printed output. This
749 means that instead of writing two different documents, one for the
750 online information and the other for a printed work, you need write only
751 one document. Therefore, when the work is revised, you need revise only
752 that one document.
753
754 Manuals for most GNU packages are written in Texinfo, and available
755 online at @url{http://www.gnu.org/doc}.
756
757 @menu
758 * Reporting Bugs:: Submitting effective bug reports.
759 * Using Texinfo:: Create printed or online output.
760 * Output Formats:: Overview of the supported output formats.
761 * Info Files:: What is an Info file?
762 * Printed Books:: Characteristics of a printed book or manual.
763 * Formatting Commands:: @@-commands are used for formatting.
764 * Conventions:: General rules for writing a Texinfo file.
765 * Comments:: Writing comments and ignored text in general.
766 * Minimum:: What a Texinfo file must have.
767 * Six Parts:: Usually, a Texinfo file has six parts.
768 * Short Sample:: A short sample Texinfo file.
769 * History:: Acknowledgements, contributors and genesis.
770 @end menu
771
772
773 @node Reporting Bugs
774 @section Reporting Bugs
775
776 @cindex Bugs, reporting
777 @cindex Suggestions for Texinfo, making
778 @cindex Reporting bugs
779 We welcome bug reports and suggestions for any aspect of the Texinfo system,
780 programs, documentation, installation, anything. Please email them to
781 @email{bug-texinfo@@gnu.org}. You can get the latest version of Texinfo
782 from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
783
784 @cindex Checklist for bug reports
785 For bug reports, please include enough information for the maintainers
786 to reproduce the problem. Generally speaking, that means:
787
788 @itemize @bullet
789 @item the version number of Texinfo and the program(s) or manual(s) involved.
790 @item hardware and operating system names and versions.
791 @item the contents of any input files necessary to reproduce the bug.
792 @item a description of the problem and samples of any erroneous output.
793 @item any unusual options you gave to @command{configure}.
794 @item anything else that you think would be helpful.
795 @end itemize
796
797 When in doubt whether something is needed or not, include it. It's
798 better to include too much than to leave out something important.
799
800 @cindex Patches, contributing
801 Patches are most welcome; if possible, please make them with
802 @samp{@w{diff -c}} (@pxref{Top,, Overview, diff, Comparing and Merging
803 Files}) and include @file{ChangeLog} entries (@pxref{Change Log,,,
804 xemacs, XEmacs User's Manual}), and follow the existing coding style.
805
806
807 @node Using Texinfo
808 @section Using Texinfo
809
810 @cindex Using Texinfo in general
811 @cindex Texinfo, introduction to
812 @cindex Introduction to Texinfo
813
814 Using Texinfo, you can create a printed document (via the @TeX{}
815 typesetting system) the normal features of a book, including chapters,
816 sections, cross references, and indices. From the same Texinfo source
817 file, you can create an Info file with special features to make
818 documentation browsing easy. You can also create from that same
819 source file an HTML output file suitable for use with a web browser,
820 or an XML file. See the next section (@pxref{Output Formats}) for
821 details and the exact commands to generate output from the source.
822
823 @TeX{} works with virtually all printers; Info works with virtually all
824 computer terminals; the HTML output works with virtually all web
825 browsers. Thus Texinfo can be used by almost any computer user.
826
827 @cindex Source file format
828 A Texinfo source file is a plain ASCII file containing text
829 interspersed with @dfn{@@-commands} (words preceded by an @samp{@@})
830 that tell the typesetting and formatting programs what to do. You can
831 edit a Texinfo file with any text editor, but it is especially
832 convenient to use XEmacs since that editor has a special mode,
833 called Texinfo mode, that provides various Texinfo-related features.
834 (@xref{Texinfo Mode}.)
835
836 You can use Texinfo to create both online help and printed manuals;
837 moreover, Texinfo is freely redistributable. For these reasons, Texinfo
838 is the official documentation format of the GNU project. More
839 information is available at the @uref{http://www.gnu.org/doc/, GNU
840 documentation web page}.
841
842
843 @node Output Formats
844 @section Output Formats
845 @cindex Output formats
846 @cindex Back-end output formats
847
848 Here is a brief overview of the output formats currently supported by
849 Texinfo.
850
851 @table @asis
852 @item Info
853 @cindex Info output
854 (Generated via @command{makeinfo}.) This format is essentially a
855 plain text transliteration of the Texinfo source. It adds a few
856 control characters to separate nodes and provide navigational
857 information for menus, cross-references, indices, and so on. See the
858 next section (@pxref{Info Files}) for more details on this format.
859 The XEmacs Info subsystem (@pxref{Top,,Getting Started,info, Info}),
860 and the standalone @command{info} program (@pxref{Top
861 ,, Info Standalone, info-stnd, GNU Info}), among others, can read these
862 files. @xref{Creating and Installing Info Files}.
863
864 @item Plain text
865 @cindex Plain text output
866 (Generated via @command{makeinfo --no-headers}.) This is almost the
867 same as Info output, except the navigational control characters are
868 omitted. Also, standard output is used by default.
869
870 @item HTML
871 @cindex HTML output
872 @cindex W3 consortium
873 @cindex Mozilla
874 @cindex Lynx
875 @cindex Emacs-W3
876 (Generated via @command{makeinfo --html}.) This is the Hyper Text
877 Markup Language that has become the most commonly used language for
878 writing documents on the World Wide Web. Web browsers, such as
879 Mozilla, Lynx, and Emacs-W3, can render this language online. There
880 are many versions of HTML; @command{makeinfo} tries to use a subset
881 of the language that can be interpreted by any common browser. For
882 details of the HTML language and much related information, see
883 @uref{http://www.w3.org/MarkUp/}. @xref{Generating HTML}.
884
885 @item DVI
886 @cindex DVI output
887 @pindex dvips
888 @pindex xdvi
889 (Generated via @command{texi2dvi}.) This DeVice Independent binary
890 format is output by the @TeX{} typesetting program
891 (@uref{http://tug.org}). This is then read by a DVI `driver', which
892 writes the actual device-specific commands that can be viewed or
893 printed, notably Dvips for translation to PostScript (@pxref{Invoking
894 Dvips,,, dvips, Dvips}) and Xdvi for viewing on an X display
895 (@uref{http://sourceforge.net/projects/xdvi/}). @xref{Hardcopy}.
896
897 Be aware that the Texinfo language is very different from and much
898 stricter than @TeX{}'s usual languages, plain @TeX{} and @LaTeX{}.
899 For more information on @TeX{} in general, please see the book
900 @cite{@TeX{} for the Impatient}, available from
901 @uref{http://savannah.gnu.org/projects/teximpatient}.
902
903 @item PDF
904 @cindex PDF output
905 @cindex Beebe, Nelson
906 @pindex pdftex
907 (Generated via @command{texi2dvi --pdf} or @command{texi2pdf}.) This
908 format was developed by Adobe Systems for portable document
909 interchange, based on their previous PostScript language. It can
910 represent the exact appearance of a document, including fonts and
911 graphics, and supporting arbitrary scaling. It is intended to be
912 platform-independent and easily viewable, among other design goals;
913 @uref{http://tug.org/TUGboat/Articles/tb22-3/tb72beebe-pdf.pdf} has
914 some background. Texinfo uses the @command{pdftex} program, a variant
915 of @TeX{}, to output PDF; see
916 @uref{http://tug.org/applications/pdftex}. @xref{PDF Output}.
917
918 @item XML
919 @cindex XML output
920 @cindex DTD, for Texinfo XML
921 @pindex texinfo.dtd
922 (Generated via @command{makeinfo --xml}.) XML is a generic syntax
923 specification usable for any sort of content (see, for example,
924 @uref{http://www.w3.org/XML/}). The @command{makeinfo} XML output,
925 unlike all the formats above, interprets very little of the Texinfo
926 source. Rather, it merely translates the Texinfo markup commands into
927 XML syntax, for processing by further XML tools. The particular
928 syntax output is defined in the file @file{texinfo.dtd} included in
929 the Texinfo source distribution.
930
931 @item Docbook
932 @cindex Docbook output
933 (Generated via @command{makeinfo --docbook}.) This is an XML-based
934 format developed some years ago, primarily for technical
935 documentation. It therefore bears some resemblance, in broad
936 outlines, to Texinfo. See @uref{http://www.docbook.org}. If you want
937 to convert from Docbook @emph{to} Texinfo, please see
938 @uref{http://docbook2X.sourceforge.net}.
939
940 @end table
941
942 @cindex Man page output, not supported
943 From time to time, proposals are made to generate traditional Unix man
944 pages from Texinfo source. However, because man pages have a very
945 strict conventional format, generating a good man page requires a
946 completely different source than the typical Texinfo applications of
947 writing a good user tutorial and/or a good reference manual. This
948 makes generating man pages incompatible with the Texinfo design goal
949 of not having to document the same information in different ways for
950 different output formats. You might as well just write the man page
951 directly.
952
953 @pindex help2man
954 @cindex O'Dea, Brendan
955 Man pages still have their place, and if you wish to support them, you
956 may find the program @command{help2man} to be useful; it generates a
957 traditional man page from the @samp{--help} output of a program. In
958 fact, this is currently used to generate man pages for the programs in
959 the Texinfo distribution. It is GNU software written by Brendan
960 O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}.
961
962 @cindex Output formats, supporting more
963 @cindex SGML-tools output format
964 If you are a programmer and would like to contribute to the GNU project
965 by implementing additional output formats for Texinfo, that would be
966 excellent. But please do not write a separate translator texi2foo for
967 your favorite format foo! That is the hard way to do the job, and makes
968 extra work in subsequent maintenance, since the Texinfo language is
969 continually being enhanced and updated. Instead, the best approach is
970 modify @code{makeinfo} to generate the new format.
971
972
973 @node Info Files
974 @section Info Files
975 @cindex Info files
976
977 An Info file is a Texinfo file formatted so that the Info documentation
978 reading program can operate on it. (@code{makeinfo}
979 and @code{texinfo-format-buffer} are two commands that convert a Texinfo file
980 into an Info file.)
981
982 Info files are divided into pieces called @dfn{nodes}, each of which
983 contains the discussion of one topic. Each node has a name, and
984 contains both text for the user to read and pointers to other nodes,
985 which are identified by their names. The Info program displays one node
986 at a time, and provides commands with which the user can move to other
987 related nodes.
988
989 @xref{Top,,, info, GNU Info}, for more information about using Info.
990
991 Each node of an Info file may have any number of child nodes that
992 describe subtopics of the node's topic. The names of child
993 nodes are listed in a @dfn{menu} within the parent node; this
994 allows you to use certain Info commands to move to one of the child
995 nodes. Generally, an Info file is organized like a book. If a node
996 is at the logical level of a chapter, its child nodes are at the level
997 of sections; likewise, the child nodes of sections are at the level
998 of subsections.
999
1000 All the children of any one parent are linked together in a
1001 bidirectional chain of `Next' and `Previous' pointers. The `Next'
1002 pointer provides a link to the next section, and the `Previous' pointer
1003 provides a link to the previous section. This means that all the nodes
1004 that are at the level of sections within a chapter are linked together.
1005 Normally the order in this chain is the same as the order of the
1006 children in the parent's menu. Each child node records the parent node
1007 name as its `Up' pointer. The last child has no `Next' pointer, and the
1008 first child has the parent both as its `Previous' and as its `Up'
1009 pointer.@footnote{In some documents, the first child has no `Previous'
1010 pointer. Occasionally, the last child has the node name of the next
1011 following higher level node as its `Next' pointer.}
1012
1013 The book-like structuring of an Info file into nodes that correspond
1014 to chapters, sections, and the like is a matter of convention, not a
1015 requirement. The `Up', `Previous', and `Next' pointers of a node can
1016 point to any other nodes, and a menu can contain any other nodes.
1017 Thus, the node structure can be any directed graph. But it is usually
1018 more comprehensible to follow a structure that corresponds to the
1019 structure of chapters and sections in a printed book or report.@refill
1020
1021 In addition to menus and to `Next', `Previous', and `Up' pointers, Info
1022 provides pointers of another kind, called references, that can be
1023 sprinkled throughout the text. This is usually the best way to
1024 represent links that do not fit a hierarchical structure.@refill
1025
1026 Usually, you will design a document so that its nodes match the
1027 structure of chapters and sections in the printed output. But
1028 occasionally there are times when this is not right for the material
1029 being discussed. Therefore, Texinfo uses separate commands to specify
1030 the node structure for the Info file and the section structure for the
1031 printed output.@refill
1032
1033 Generally, you enter an Info file through a node that by convention is
1034 named `Top'. This node normally contains just a brief summary of the
1035 file's purpose, and a large menu through which the rest of the file is
1036 reached. From this node, you can either traverse the file
1037 systematically by going from node to node, or you can go to a specific
1038 node listed in the main menu, or you can search the index menus and then
1039 go directly to the node that has the information you want. Alternatively,
1040 with the standalone Info program, you can specify specific menu items on
1041 the command line (@pxref{Top,,, info, Info}).
1042
1043 If you want to read through an Info file in sequence, as if it were a
1044 printed manual, you can hit @key{SPC} repeatedly, or you get the whole
1045 file with the advanced Info command @kbd{g *}. (@inforef{Advanced,
1046 Advanced Info commands, info}.)@refill
1047
1048 @c !!! dir file may be located in one of many places:
1049 @c /usr/local/xemacs/info mentioned in info.c DEFAULT_INFOPATH
1050 @c /usr/local/lib/xemacs/info mentioned in info.c DEFAULT_INFOPATH
1051 @c /usr/gnu/info mentioned in info.c DEFAULT_INFOPATH
1052 @c /usr/local/info
1053 @c /usr/local/lib/info
1054 The @file{dir} file in the @file{info} directory serves as the
1055 departure point for the whole Info system. From it, you can reach the
1056 `Top' nodes of each of the documents in a complete Info system.@refill
1057
1058 @cindex URI syntax for Info
1059 If you wish to refer to an Info file in a URI, you can use the
1060 (unofficial) syntax exemplified in the following. This works with
1061 Emacs/W3, for example:
1062 @example
1063 info:///usr/info/xemacs#Dissociated%20Press
1064 info:xemacs#Dissociated%20Press
1065 info://localhost/usr/info/xemacs#Dissociated%20Press
1066 @end example
1067
1068 The @command{info} program itself does not follow URIs of any kind.
1069
1070
1071 @node Printed Books
1072 @section Printed Books
1073 @cindex Printed book and manual characteristics
1074 @cindex Manual characteristics, printed
1075 @cindex Book characteristics, printed
1076 @cindex Texinfo printed book characteristics
1077 @cindex Characteristics, printed books or manuals
1078
1079 @cindex Knuth, Donald
1080 A Texinfo file can be formatted and typeset as a printed book or manual.
1081 To do this, you need @TeX{}, a powerful, sophisticated typesetting
1082 program written by Donald Knuth.@footnote{You can also use the
1083 @pindex texi2roff@r{, unsupported software}
1084 @uref{ftp://tug.org/texi2roff.tar.gz, @code{texi2roff}} program if you
1085 do not have @TeX{}; since Texinfo is designed for use with @TeX{},
1086 @code{texi2roff} is not described here. @code{texi2roff} is not part of
1087 the standard GNU distribution and is not maintained or up-to-date with
1088 all the Texinfo features described in this manual.}
1089
1090 A Texinfo-based book is similar to any other typeset, printed work: it
1091 can have a title page, copyright page, table of contents, and preface,
1092 as well as chapters, numbered or unnumbered sections and subsections,
1093 page headers, cross references, footnotes, and indices.@refill
1094
1095 You can use Texinfo to write a book without ever having the intention
1096 of converting it into online information. You can use Texinfo for
1097 writing a printed novel, and even to write a printed memo, although
1098 this latter application is not recommended since electronic mail is so
1099 much easier.@refill
1100
1101 @TeX{} is a general purpose typesetting program. Texinfo provides a
1102 file @file{texinfo.tex} that contains information (definitions or
1103 @dfn{macros}) that @TeX{} uses when it typesets a Texinfo file.
1104 (@file{texinfo.tex} tells @TeX{} how to convert the Texinfo @@-commands
1105 to @TeX{} commands, which @TeX{} can then process to create the typeset
1106 document.) @file{texinfo.tex} contains the specifications for printing
1107 a document. You can get the latest version of @file{texinfo.tex} from
1108 the Texinfo home page, @uref{http://www.gnu.org/software/texinfo/}.
1109
1110 In the United States, documents are most often printed on 8.5 inch by 11
1111 inch pages (216@dmn{mm} by 280@dmn{mm}); this is the default size. But
1112 you can also print for 7 inch by 9.25 inch pages (178@dmn{mm} by
1113 235@dmn{mm}, the @code{@@smallbook} size; or on A4 or A5 size paper
1114 (@code{@@afourpaper}, @code{@@afivepaper}). (@xref{smallbook, ,
1115 Printing ``Small'' Books}. Also, see @ref{A4 Paper, ,Printing on A4
1116 Paper}.)
1117
1118 By changing the parameters in @file{texinfo.tex}, you can change the
1119 size of the printed document. In addition, you can change the style in
1120 which the printed document is formatted; for example, you can change the
1121 sizes and fonts used, the amount of indentation for each paragraph, the
1122 degree to which words are hyphenated, and the like. By changing the
1123 specifications, you can make a book look dignified, old and serious, or
1124 light-hearted, young and cheery.
1125
1126 @TeX{} is freely distributable. It is written in a superset of Pascal
1127 called WEB and can be compiled either in Pascal or (by using a
1128 conversion program that comes with the @TeX{} distribution) in C.
1129 (@xref{TeX Mode, ,@TeX{} Mode, xemacs, XEmacs User's Manual}, for information
1130 about @TeX{}.)@refill
1131
1132 @TeX{} is very powerful and has a great many features. Because a
1133 Texinfo file must be able to present information both on a
1134 character-only terminal in Info form and in a typeset book, the
1135 formatting commands that Texinfo supports are necessarily limited.
1136
1137 To get a copy of @TeX{}, see
1138 @ref{Obtaining TeX, , How to Obtain @TeX{}}.
1139
1140
1141 @node Formatting Commands
1142 @section @@-commands
1143 @cindex @@-commands
1144 @cindex Formatting commands
1145
1146 In a Texinfo file, the commands that tell @TeX{} how to typeset the
1147 printed manual and tell @code{makeinfo} and
1148 @code{texinfo-format-buffer} how to create an Info file are preceded
1149 by @samp{@@}; they are called @dfn{@@-commands}. For example,
1150 @code{@@node} is the command to indicate a node and @code{@@chapter}
1151 is the command to indicate the start of a chapter.@refill
1152
1153 @quotation Note
1154 Almost all @@ command names are entirely lower case.
1155 @end quotation
1156
1157 The Texinfo @@-commands are a strictly limited set of constructs. The
1158 strict limits make it possible for Texinfo files to be understood both
1159 by @TeX{} and by the code that converts them into Info files. You can
1160 display Info files on any terminal that displays alphabetic and
1161 numeric characters. Similarly, you can print the output generated by
1162 @TeX{} on a wide variety of printers.@refill
1163
1164 Depending on what they do or what arguments@footnote{The word
1165 @dfn{argument} comes from the way it is used in mathematics and does not
1166 refer to a dispute between two people; it refers to the information
1167 presented to the command. According to the @cite{Oxford English
1168 Dictionary}, the word derives from the Latin for @dfn{to make clear,
1169 prove}; thus it came to mean `the evidence offered as proof', which is
1170 to say, `the information offered', which led to its mathematical
1171 meaning. In its other thread of derivation, the word came to mean `to
1172 assert in a manner against which others may make counter assertions',
1173 which led to the meaning of `argument' as a dispute.} they take, you
1174 need to write @@-commands on lines of their own or as part of
1175 sentences:
1176
1177 @itemize @bullet
1178 @item
1179 Write a command such as @code{@@quotation} at the beginning of a line as
1180 the only text on the line. (@code{@@quotation} begins an indented
1181 environment.)
1182
1183 @item
1184 Write a command such as @code{@@chapter} at the beginning of a line
1185 followed by the command's arguments, in this case the chapter title, on
1186 the rest of the line. (@code{@@chapter} creates chapter titles.)@refill
1187
1188 @item
1189 Write a command such as @code{@@dots@{@}} wherever you wish but usually
1190 within a sentence. (@code{@@dots@{@}} creates an ellipsis @dots{})@refill
1191
1192 @item
1193 Write a command such as @code{@@code@{@var{sample-code}@}} wherever you
1194 wish (but usually within a sentence) with its argument,
1195 @var{sample-code} in this example, between the braces. (@code{@@code}
1196 marks text as being code.)@refill
1197
1198 @item
1199 Write a command such as @code{@@example} on a line of its own; write the
1200 body-text on following lines; and write the matching @code{@@end}
1201 command, @code{@@end example} in this case, on a line of its own
1202 after the body-text. (@code{@@example} @dots{} @code{@@end example}
1203 indents and typesets body-text as an example.) It's usually ok to
1204 indent environment commands like this, but in complicated and
1205 hard-to-define circumstances the extra spaces cause extra space to
1206 appear in the output, so beware.
1207 @end itemize
1208
1209 @noindent
1210 @cindex Braces, when to use
1211 As a general rule, a command requires braces if it mingles among other
1212 text; but it does not need braces if it starts a line of its own. The
1213 non-alphabetic commands, such as @code{@@:}, are exceptions to the rule;
1214 they do not need braces.@refill
1215
1216 As you gain experience with Texinfo, you will rapidly learn how to
1217 write the different commands: the different ways to write commands
1218 actually make it easier to write and read Texinfo files than if all
1219 commands followed exactly the same syntax. @xref{Command Syntax, ,
1220 @@-Command Syntax}, for all the details.
1221
1222
1223 @node Conventions
1224 @section General Syntactic Conventions
1225 @cindex General syntactic conventions
1226 @cindex Syntactic conventions
1227 @cindex Conventions, syntactic
1228 @cindex Characters, basic input
1229
1230 This section describes the general conventions used in all Texinfo documents.
1231
1232 @itemize @bullet
1233 @item
1234 @cindex Source files, characters used
1235 All printable ASCII characters except @samp{@@}, @samp{@{} and
1236 @samp{@}} can appear in a Texinfo file and stand for themselves.
1237 @samp{@@} is the escape character which introduces commands, while
1238 @samp{@{} and @samp{@}} are used to surround arguments to certain
1239 commands. To put one of these special characters into the document, put
1240 an @samp{@@} character in front of it, like this: @samp{@@@@},
1241 @samp{@@@{}, and @samp{@@@}}.
1242
1243 @item
1244 @cindex Paragraph separator
1245 @cindex Blank lines, as paragraph separator
1246 @cindex Newlines, as blank lines
1247 Separate paragraphs with one or more blank lines. Currently Texinfo
1248 only recognizes newline characters as end of line, not the CRLF
1249 sequence used on some systems; so a @dfn{blank line} means exactly two
1250 consecutive newlines. Sometimes blank lines are useful or convenient
1251 in other cases as well; you can use the @code{@@noindent} to inhibit
1252 paragraph indentation if required (@pxref{noindent,,@code{@@noindent}}).
1253
1254 @item
1255 Texinfo supports the usual quotation marks used in English, and
1256 quotation marks used in other languages, please see @ref{Inserting
1257 Quotation Marks}.
1258
1259 @item
1260 @cindex Multiple dashes in source
1261 @cindex Dashes in source
1262 @cindex Hyphens in source, two or three in a row
1263 @cindex Em dash, producing
1264 @cindex En dash, producing
1265 Use three hyphens in a row, @samp{---}, to produce a long dash---like
1266 this (called an @dfn{em dash}), used for punctuation in sentences.
1267 Use two hyphens, @samp{--}, to produce a medium dash (called an
1268 @dfn{en dash}), used primarily for numeric ranges, as in ``June
1269 25--26''. Use a single hyphen, @samp{-}, to produce a standard hyphen
1270 used in compound words. For display on the screen, Info reduces three
1271 hyphens to two and two hyphens to one (not transitively!). Of course,
1272 any number of hyphens in the source remain as they are in literal
1273 contexts, such as @code{@@code} and @code{@@example}.
1274
1275 @item
1276 @cindex Tabs; don't use!
1277 @strong{Caution:} Last, do not use tab characters in a Texinfo file
1278 (except in verbatim modes)! @TeX{} uses variable-width fonts, which
1279 means that it is impractical at best to define a tab to work in all
1280 circumstances. Consequently, @TeX{} treats tabs like single spaces,
1281 and that is not what they look like in the source. Furthermore,
1282 @code{makeinfo} does nothing special with tabs, and thus a tab
1283 character in your input file will usually appear differently in the
1284 output.
1285
1286 @noindent
1287 To avoid this problem, Texinfo mode in XEmacs inserts
1288 multiple spaces when you press the @key{TAB} key. Also, you can run
1289 @code{untabify} in XEmacs to convert tabs in a region to multiple
1290 spaces, or use the @code{unexpand} command from the shell.
1291
1292 @end itemize
1293
1294
1295 @node Comments
1296 @section Comments
1297
1298 @cindex Comments
1299 @findex comment
1300 @findex c @r{(comment)}
1301
1302 You can write comments in a Texinfo file that will not appear in
1303 either the Info file or the printed manual by using the
1304 @code{@@comment} command (which may be abbreviated to @code{@@c}).
1305 Such comments are for the person who revises the Texinfo file. All the
1306 text on a line that follows either @code{@@comment} or @code{@@c} is a
1307 comment; the rest of the line does not appear in either the Info file
1308 or the printed manual.
1309
1310 Often, you can write the @code{@@comment} or @code{@@c} in the middle of
1311 a line, and only the text that follows after the @code{@@comment} or
1312 @code{@@c} command does not appear; but some commands, such as
1313 @code{@@settitle} and @code{@@setfilename}, work on a whole line. You
1314 cannot use @code{@@comment} or @code{@@c} in a line beginning with such
1315 a command.
1316
1317 @cindex Ignored text
1318 @cindex Unprocessed text
1319 @findex ignore
1320 You can write long stretches of text that will not appear in either
1321 the Info file or the printed manual by using the @code{@@ignore} and
1322 @code{@@end ignore} commands. Write each of these commands on a line
1323 of its own, starting each command at the beginning of the line. Text
1324 between these two commands does not appear in the processed output.
1325 You can use @code{@@ignore} and @code{@@end ignore} for writing
1326 comments.
1327
1328 Text enclosed by @code{@@ignore} or by failing @code{@@ifset} or
1329 @code{@@ifclear} conditions is ignored in the sense that it will not
1330 contribute to the formatted output. However, @TeX{} and makeinfo must
1331 still parse the ignored text, in order to understand when to @emph{stop}
1332 ignoring text from the source file; that means that you may still get
1333 error messages if you have invalid Texinfo commands within ignored text.
1334
1335
1336 @node Minimum
1337 @section What a Texinfo File Must Have
1338 @cindex Minimal Texinfo file (requirements)
1339 @cindex Must have in Texinfo file
1340 @cindex Required in Texinfo file
1341 @cindex Texinfo file minimum
1342
1343 By convention, the name of a Texinfo file ends with (in order of
1344 preference) one of the extensions @file{.texinfo}, @file{.texi},
1345 @file{.txi}, or @file{.tex}. The longer extensions are preferred since
1346 they describe more clearly to a human reader the nature of the file.
1347 The shorter extensions are for operating systems that cannot handle long
1348 file names.
1349
1350 In order to be made into a printed manual and an Info file, a Texinfo
1351 file @strong{must} begin with lines like this:
1352
1353 @example
1354 @group
1355 \input texinfo
1356 @@setfilename @var{info-file-name}
1357 @@settitle @var{name-of-manual}
1358 @end group
1359 @end example
1360
1361 @noindent
1362 The contents of the file follow this beginning, and then you
1363 @strong{must} end a Texinfo file with a line like this:
1364
1365 @example
1366 @@bye
1367 @end example
1368
1369 @findex \input @r{(raw @TeX{} startup)}
1370 @noindent
1371 Here's an explanation:
1372
1373 @itemize @bullet
1374 @item
1375 The @samp{\input texinfo} line tells @TeX{} to use the
1376 @file{texinfo.tex} file, which tells @TeX{} how to translate the Texinfo
1377 @@-commands into @TeX{} typesetting commands. (Note the use of the
1378 backslash, @samp{\}; this is correct for @TeX{}.)
1379
1380 @item
1381 The @code{@@setfilename} line provides a name for the Info file and
1382 tells @TeX{} to open auxiliary files. @strong{All text before
1383 @code{@@setfilename} is ignored!}
1384
1385 @item
1386 The @code{@@settitle} line specifies a title for the page headers (or
1387 footers) of the printed manual, and the default document description for
1388 the @samp{<head>} in HTML format. Strictly speaking, @code{@@settitle}
1389 is optional---if you don't mind your document being titled `Untitled'.
1390
1391 @item
1392 The @code{@@bye} line at the end of the file on a line of its own tells
1393 the formatters that the file is ended and to stop formatting.
1394
1395 @end itemize
1396
1397 Typically, you will not use quite such a spare format, but will include
1398 mode setting and start-of-header and end-of-header lines at the
1399 beginning of a Texinfo file, like this:
1400
1401 @example
1402 @group
1403 \input texinfo @@c -*-texinfo-*-
1404 @@c %**start of header
1405 @@setfilename @var{info-file-name}
1406 @@settitle @var{name-of-manual}
1407 @@c %**end of header
1408 @end group
1409 @end example
1410
1411 @noindent
1412 In the first line, @samp{-*-texinfo-*-} causes XEmacs to switch into
1413 Texinfo mode when you edit the file.
1414
1415 The @code{@@c} lines which surround the @code{@@setfilename} and
1416 @code{@@settitle} lines are optional, but you need them in order to
1417 run @TeX{} or Info on just part of the file. (@xref{Start of Header}.)
1418
1419 Furthermore, you will usually provide a Texinfo file with a title page,
1420 indices, and the like, all of which are explained in this manual. But
1421 the minimum, which can be useful for short documents, is just the three
1422 lines at the beginning and the one line at the end.
1423
1424
1425 @node Six Parts
1426 @section Six Parts of a Texinfo File
1427
1428 Generally, a Texinfo file contains more than the minimal beginning and
1429 end described in the previous section---it usually contains the six
1430 parts listed below. These are described fully in the following sections.
1431
1432 @table @r
1433 @item 1. Header
1434 The @dfn{Header} names the file, tells @TeX{} which definitions file to
1435 use, and other such housekeeping tasks.
1436
1437 @item 2. Summary and Copyright
1438 The @dfn{Summary and Copyright} segment describes the document and
1439 contains the copyright notice and copying permissions. This is done
1440 with the @code{@@copying} command.
1441
1442 @item 3. Title and Copyright
1443 The @dfn{Title and Copyright} segment contains the title and copyright
1444 pages for the printed manual. The segment must be enclosed between
1445 @code{@@titlepage} and @code{@@end titlepage} commands. The title and
1446 copyright page appear only in the printed manual.
1447
1448 @item 4. `Top' Node and Master Menu
1449 The `Top' node starts off the online output; it does not appear in the
1450 printed manual. We recommend including the copying permissions here as
1451 well as the segments above. And it contains at least a top-level menu
1452 listing the chapters, and possibly a @dfn{Master Menu} listing all the
1453 nodes in the entire document.
1454
1455 @item 5. Body
1456 The @dfn{Body} of the document is typically structured like a
1457 traditional book or encyclopedia, but it may be free form.
1458
1459 @item 6. End
1460 The @dfn{End} segment may contain commands for printing indices, and
1461 closes with the @code{@@bye} command on a line of its own.
1462 @end table
1463
1464
1465 @node Short Sample
1466 @section A Short Sample Texinfo File
1467 @cindex Sample Texinfo file, with comments
1468
1469 Here is a very short but complete Texinfo file, in the six conventional
1470 parts enumerated in the previous section, so you can see how Texinfo
1471 source appears in practice. The first three parts of the file, from
1472 @samp{\input texinfo} through to @samp{@@end titlepage}, look more
1473 intimidating than they are: most of the material is standard
1474 boilerplate; when writing a manual, you simply change the names as
1475 appropriate.
1476
1477 @xref{Beginning a File}, for full documentation on the commands listed
1478 here. @xref{GNU Sample Texts}, for the full texts to be used in GNU
1479 manuals.
1480
1481 In the following, the sample text is @emph{indented}; comments on it are
1482 not. The complete file, without interspersed comments, is shown in
1483 @ref{Short Sample Texinfo File}.
1484
1485 @subheading Part 1: Header
1486
1487 @noindent
1488 The header does not appear in either the Info file or the
1489 printed output. It sets various parameters, including the
1490 name of the Info file and the title used in the header.
1491
1492 @example
1493 @group
1494 \input texinfo @@c -*-texinfo-*-
1495 @@c %**start of header
1496 @@setfilename sample.info
1497 @@settitle Sample Manual 1.0
1498 @@c %**end of header
1499 @end group
1500 @end example
1501
1502 @subheading Part 2: Summary Description and Copyright
1503
1504 @noindent
1505 A real manual includes more text here, according to the license under
1506 which it is distributed. @xref{GNU Sample Texts}.
1507
1508 @example
1509 @group
1510 @@copying
1511 This is a short example of a complete Texinfo file, version 1.0.
1512
1513 Copyright @@copyright@{@} 2005 Free Software Foundation, Inc.
1514 @@end copying
1515 @end group
1516 @end example
1517
1518 @subheading Part 3: Titlepage, Contents, Copyright
1519
1520 @noindent
1521 The titlepage segment does not appear in the online output, only in the
1522 printed manual. We use the @code{@@insertcopying} command to
1523 include the permission text from the previous section, instead of
1524 writing it out again; it is output on the back of the title page. The
1525 @code{@@contents} command generates a table of contents.
1526
1527 @example
1528 @group
1529 @@titlepage
1530 @@title Sample Title
1531 @end group
1532
1533 @group
1534 @@c The following two commands start the copyright page.
1535 @@page
1536 @@vskip 0pt plus 1filll
1537 @@insertcopying
1538 @@end titlepage
1539 @end group
1540
1541 @@c Output the table of contents at the beginning.
1542 @@contents
1543 @end example
1544
1545 @subheading Part 4: `Top' Node and Master Menu
1546
1547 @noindent
1548 The `Top' node contains the master menu for the Info file. Since the
1549 printed manual uses a table of contents rather than a menu, it
1550 excludes the `Top' node. We repeat the short description from the
1551 beginning of the @samp{@@copying} text, but there's no need to repeat
1552 the copyright information, so we don't use @samp{@@insertcopying} here.
1553 The @samp{@@top} command itself helps @command{makeinfo} determine the
1554 relationships between nodes.
1555
1556 @example
1557 @@ifnottex
1558 @@node Top
1559 @@top Short Sample
1560
1561 This is a short sample Texinfo file.
1562 @@end ifnottex
1563
1564 @group
1565 @@menu
1566 * First Chapter:: The first chapter is the
1567 only chapter in this sample.
1568 * Index:: Complete index.
1569 @@end menu
1570 @end group
1571 @end example
1572
1573
1574 @subheading Part 5: The Body of the Document
1575
1576 @noindent
1577 The body segment contains all the text of the document, but not the
1578 indices or table of contents. This example illustrates a node and a
1579 chapter containing an enumerated list.
1580
1581 @example
1582 @group
1583 @@node First Chapter
1584 @@chapter First Chapter
1585
1586 @@cindex chapter, first
1587 @end group
1588
1589 @group
1590 This is the first chapter.
1591 @@cindex index entry, another
1592 @end group
1593
1594 @group
1595 Here is a numbered list.
1596
1597 @@enumerate
1598 @@item
1599 This is the first item.
1600
1601 @@item
1602 This is the second item.
1603 @@end enumerate
1604 @end group
1605 @end example
1606
1607
1608 @subheading Part 6: The End of the Document
1609
1610 @noindent
1611 The end segment contains commands for generating an index in a node and
1612 unnumbered chapter of its own, and the @code{@@bye} command that marks
1613 the end of the document.
1614
1615 @example
1616 @group
1617 @@node Index
1618 @@unnumbered Index
1619 @end group
1620
1621 @group
1622 @@printindex cp
1623
1624 @@bye
1625 @end group
1626 @end example
1627
1628
1629 @subheading Some Results
1630
1631 Here is what the contents of the first chapter of the sample look like:
1632
1633 @sp 1
1634 @need 700
1635 @quotation
1636 This is the first chapter.
1637
1638 Here is a numbered list.
1639
1640 @enumerate
1641 @item
1642 This is the first item.
1643
1644 @item
1645 This is the second item.
1646 @end enumerate
1647 @end quotation
1648
1649
1650 @node History
1651 @section History
1652
1653 @cindex Stallman, Richard M.
1654 @cindex Chassell, Robert J.
1655 @cindex Fox, Brian
1656 @cindex Berry, Karl
1657 Richard M. Stallman invented the Texinfo format, wrote the initial
1658 processors, and created Edition 1.0 of this manual. Robert@tie{}J.
1659 Chassell greatly revised and extended the manual, starting with
1660 Edition 1.1. Brian Fox was responsible for the standalone Texinfo
1661 distribution until version 3.8, and wrote the standalone
1662 @command{makeinfo} and @command{info} programs. Karl Berry has
1663 continued maintenance since Texinfo 3.8 (manual edition 2.22).
1664
1665 @cindex Pinard, Fran@,{c}ois
1666 @cindex Zuhn, David D.
1667 @cindex Weisshaus, Melissa
1668 @cindex Zaretskii, Eli
1669 @cindex Schwab, Andreas
1670 @cindex Weinberg, Zack
1671 Our thanks go out to all who helped improve this work, particularly the
1672 indefatigable Eli Zaretskii and Andreas Schwab, who have provided
1673 patches beyond counting. Fran@,{c}ois Pinard and David@tie{}D. Zuhn,
1674 tirelessly recorded and reported mistakes and obscurities. Zack
1675 Weinberg did the impossible by implementing the macro syntax in
1676 @file{texinfo.tex}. Special thanks go to Melissa Weisshaus for her
1677 frequent reviews of nearly similar editions. Dozens of others have
1678 contributed patches and suggestions, they are gratefully acknowledged in
1679 the @file{ChangeLog} file. Our mistakes are our own.
1680
1681 @cindex Scribe
1682 @cindex Reid, Brian
1683 @cindex History of Texinfo
1684 @cindex Texinfo history
1685 A bit of history: in the 1970's at CMU, Brian Reid developed a program
1686 and format named Scribe to mark up documents for printing. It used the
1687 @code{@@} character to introduce commands, as Texinfo does. Much more
1688 consequentially, it strove to describe document contents rather than
1689 formatting, an idea wholeheartedly adopted by Texinfo.
1690
1691 @cindex Bolio
1692 @cindex Bo@TeX{}
1693 Meanwhile, people at MIT developed another, not too dissimilar format
1694 called Bolio. This then was converted to using @TeX{} as its typesetting
1695 language: Bo@TeX{}. The earliest Bo@TeX{} version seems to have been
1696 0.02 on October 31, 1984.
1697
1698 Bo@TeX{} could only be used as a markup language for documents to be
1699 printed, not for online documents. Richard Stallman (RMS) worked on
1700 both Bolio and Bo@TeX{}. He also developed a nifty on-line help format
1701 called Info, and then combined Bo@TeX{} and Info to create Texinfo, a
1702 mark up language for text that is intended to be read both online and
1703 as printed hard copy.
1704
1705
1706 @node Texinfo Mode
1707 @chapter Using Texinfo Mode
1708 @cindex Texinfo mode
1709 @cindex Mode, using Texinfo
1710 @cindex XEmacs
1711
1712 You may edit a Texinfo file with any text editor you choose. A Texinfo
1713 file is no different from any other ASCII file. However, XEmacs
1714 comes with a special mode, called Texinfo mode, that provides XEmacs
1715 commands and tools to help ease your work.
1716
1717 This chapter describes features of XEmacs' Texinfo mode but not any
1718 features of the Texinfo formatting language. So if you are reading this
1719 manual straight through from the beginning, you may want to skim through
1720 this chapter briefly and come back to it after reading succeeding
1721 chapters which describe the Texinfo formatting language in detail.
1722
1723 @menu
1724 * Texinfo Mode Overview:: How Texinfo mode can help you.
1725 * XEmacs Editing:: Texinfo mode adds to XEmacs' general
1726 purpose editing features.
1727 * Inserting:: How to insert frequently used @@-commands.
1728 * Showing the Structure:: How to show the structure of a file.
1729 * Updating Nodes and Menus:: How to update or create new nodes and menus.
1730 * Info Formatting:: How to format for Info.
1731 * Printing:: How to format and print part or all of a file.
1732 * Texinfo Mode Summary:: Summary of all the Texinfo mode commands.
1733 @end menu
1734
1735 @node Texinfo Mode Overview
1736 @section Texinfo Mode Overview
1737
1738 Texinfo mode provides special features for working with Texinfo files.
1739 You can:
1740
1741 @itemize @bullet
1742 @item
1743 Insert frequently used @@-commands. @refill
1744
1745 @item
1746 Automatically create @code{@@node} lines.
1747
1748 @item
1749 Show the structure of a Texinfo source file.@refill
1750
1751 @item
1752 Automatically create or update the `Next',
1753 `Previous', and `Up' pointers of a node.
1754
1755 @item
1756 Automatically create or update menus.@refill
1757
1758 @item
1759 Automatically create a master menu.@refill
1760
1761 @item
1762 Format a part or all of a file for Info.@refill
1763
1764 @item
1765 Typeset and print part or all of a file.@refill
1766 @end itemize
1767
1768 Perhaps the two most helpful features are those for inserting frequently
1769 used @@-commands and for creating node pointers and menus.@refill
1770
1771 @node XEmacs Editing
1772 @section The Usual XEmacs Editing Commands
1773
1774 In most cases, the usual Text mode commands work the same in Texinfo
1775 mode as they do in Text mode. Texinfo mode adds new editing commands
1776 and tools to XEmacs' general purpose editing features. The major
1777 difference concerns filling. In Texinfo mode, the paragraph
1778 separation variable and syntax table are redefined so that Texinfo
1779 commands that should be on lines of their own are not inadvertently
1780 included in paragraphs. Thus, the @kbd{M-q} (@code{fill-paragraph})
1781 command will refill a paragraph but not mix an indexing command on a
1782 line adjacent to it into the paragraph.@refill
1783
1784 In addition, Texinfo mode sets the @code{page-delimiter} variable to
1785 the value of @code{texinfo-chapter-level-regexp}; by default, this is
1786 a regular expression matching the commands for chapters and their
1787 equivalents, such as appendices. With this value for the page
1788 delimiter, you can jump from chapter title to chapter title with the
1789 @kbd{C-x ]} (@code{forward-page}) and @kbd{C-x [}
1790 (@code{backward-page}) commands and narrow to a chapter with the
1791 @kbd{C-x n p} (@code{narrow-to-page}) command. (@xref{Pages, , ,xemacs,
1792 XEmacs User's Manual}, for details about the page commands.)@refill
1793
1794 You may name a Texinfo file however you wish, but the convention is to
1795 end a Texinfo file name with one of the extensions
1796 @file{.texinfo}, @file{.texi}, @file{.txi}, or @file{.tex}. A longer
1797 extension is preferred, since it is explicit, but a shorter extension
1798 may be necessary for operating systems that limit the length of file
1799 names. XEmacs automatically enters Texinfo mode when you visit a
1800 file with a @file{.texinfo}, @file{.texi} or @file{.txi}
1801 extension. Also, XEmacs switches to Texinfo mode
1802 when you visit a
1803 file that has @samp{-*-texinfo-*-} in its first line. If ever you are
1804 in another mode and wish to switch to Texinfo mode, type @code{M-x
1805 texinfo-mode}.@refill
1806
1807 Like all other XEmacs features, you can customize or enhance Texinfo
1808 mode as you wish. In particular, the keybindings are very easy to
1809 change. The keybindings described here are the default or standard
1810 ones.@refill
1811
1812 @node Inserting
1813 @comment node-name, next, previous, up
1814 @section Inserting Frequently Used Commands
1815 @cindex Inserting frequently used commands
1816 @cindex Frequently used commands, inserting
1817 @cindex Commands, inserting them
1818
1819 Texinfo mode provides commands to insert various frequently used
1820 @@-commands into the buffer. You can use these commands to save
1821 keystrokes.@refill
1822
1823 The insert commands are invoked by typing @kbd{C-c} twice and then the
1824 first letter of the @@-command:@refill
1825
1826 @table @kbd
1827 @item C-c C-c c
1828 @itemx M-x texinfo-insert-@@code
1829 @findex texinfo-insert-@@code
1830 Insert @code{@@code@{@}} and put the
1831 cursor between the braces.@refill
1832
1833 @item C-c C-c d
1834 @itemx M-x texinfo-insert-@@dfn
1835 @findex texinfo-insert-@@dfn
1836 Insert @code{@@dfn@{@}} and put the
1837 cursor between the braces.@refill
1838
1839 @item C-c C-c e
1840 @itemx M-x texinfo-insert-@@end
1841 @findex texinfo-insert-@@end
1842 Insert @code{@@end} and attempt to insert the correct following word,
1843 such as @samp{example} or @samp{table}. (This command does not handle
1844 nested lists correctly, but inserts the word appropriate to the
1845 immediately preceding list.)@refill
1846
1847 @item C-c C-c i
1848 @itemx M-x texinfo-insert-@@item
1849 @findex texinfo-insert-@@item
1850 Insert @code{@@item} and put the
1851 cursor at the beginning of the next line.@refill
1852
1853 @item C-c C-c k
1854 @itemx M-x texinfo-insert-@@kbd
1855 @findex texinfo-insert-@@kbd
1856 Insert @code{@@kbd@{@}} and put the
1857 cursor between the braces.@refill
1858
1859 @item C-c C-c n
1860 @itemx M-x texinfo-insert-@@node
1861 @findex texinfo-insert-@@node
1862 Insert @code{@@node} and a comment line
1863 listing the sequence for the `Next',
1864 `Previous', and `Up' nodes.
1865 Leave point after the @code{@@node}.@refill
1866
1867 @item C-c C-c o
1868 @itemx M-x texinfo-insert-@@noindent
1869 @findex texinfo-insert-@@noindent
1870 Insert @code{@@noindent} and put the
1871 cursor at the beginning of the next line.@refill
1872
1873 @item C-c C-c s
1874 @itemx M-x texinfo-insert-@@samp
1875 @findex texinfo-insert-@@samp
1876 Insert @code{@@samp@{@}} and put the
1877 cursor between the braces.@refill
1878
1879 @item C-c C-c t
1880 @itemx M-x texinfo-insert-@@table
1881 @findex texinfo-insert-@@table
1882 Insert @code{@@table} followed by a @key{SPC}
1883 and leave the cursor after the @key{SPC}.@refill
1884
1885 @item C-c C-c v
1886 @itemx M-x texinfo-insert-@@var
1887 @findex texinfo-insert-@@var
1888 Insert @code{@@var@{@}} and put the
1889 cursor between the braces.@refill
1890
1891 @item C-c C-c x
1892 @itemx M-x texinfo-insert-@@example
1893 @findex texinfo-insert-@@example
1894 Insert @code{@@example} and put the
1895 cursor at the beginning of the next line.@refill
1896
1897 @c M-@{ was the binding for texinfo-insert-braces;
1898 @c in Emacs 19, backward-paragraph will take this binding.
1899 @item C-c C-c @{
1900 @itemx M-x texinfo-insert-braces
1901 @findex texinfo-insert-braces
1902 Insert @code{@{@}} and put the cursor between the braces.@refill
1903
1904 @item C-c @}
1905 @itemx C-c ]
1906 @itemx M-x up-list
1907 @findex up-list
1908 Move from between a pair of braces forward past the closing brace.
1909 Typing @kbd{C-c ]} is easier than typing @kbd{C-c @}}, which
1910 is, however, more mnemonic; hence the two keybindings. (Also, you can
1911 move out from between braces by typing @kbd{C-f}.)@refill
1912 @end table
1913
1914 To put a command such as @w{@code{@@code@{@dots{}@}}} around an
1915 @emph{existing} word, position the cursor in front of the word and type
1916 @kbd{C-u 1 C-c C-c c}. This makes it easy to edit existing plain text.
1917 The value of the prefix argument tells XEmacs how many words following
1918 point to include between braces---@samp{1} for one word, @samp{2} for
1919 two words, and so on. Use a negative argument to enclose the previous
1920 word or words. If you do not specify a prefix argument, XEmacs inserts
1921 the @@-command string and positions the cursor between the braces. This
1922 feature works only for those @@-commands that operate on a word or words
1923 within one line, such as @code{@@kbd} and @code{@@var}.@refill
1924
1925 This set of insert commands was created after analyzing the frequency
1926 with which different @@-commands are used in the @cite{XEmacs
1927 Manual} and the @cite{GDB Manual}. If you wish to add your own insert
1928 commands, you can bind a keyboard macro to a key, use abbreviations,
1929 or extend the code in @file{texinfo.el}.@refill
1930
1931 @findex texinfo-start-menu-description
1932 @cindex Menu description, start
1933 @cindex Description for menu, start
1934 @kbd{C-c C-c C-d} (@code{texinfo-start-menu-description}) is an insert
1935 command that works differently from the other insert commands. It
1936 inserts a node's section or chapter title in the space for the
1937 description in a menu entry line. (A menu entry has three parts, the
1938 entry name, the node name, and the description. Only the node name is
1939 required, but a description helps explain what the node is about.
1940 @xref{Menu Parts, , The Parts of a Menu}.)@refill
1941
1942 To use @code{texinfo-start-menu-description}, position point in a menu
1943 entry line and type @kbd{C-c C-c C-d}. The command looks for and copies
1944 the title that goes with the node name, and inserts the title as a
1945 description; it positions point at beginning of the inserted text so you
1946 can edit it. The function does not insert the title if the menu entry
1947 line already contains a description.@refill
1948
1949 This command is only an aid to writing descriptions; it does not do the
1950 whole job. You must edit the inserted text since a title tends to use
1951 the same words as a node name but a useful description uses different
1952 words.@refill
1953
1954 @node Showing the Structure
1955 @comment node-name, next, previous, up
1956 @section Showing the Section Structure of a File
1957 @cindex Showing the section structure of a file
1958 @cindex Section structure of a file, showing it
1959 @cindex Structure of a file, showing it
1960 @cindex Outline of file structure, showing it
1961 @cindex Contents-like outline of file structure
1962 @cindex File section structure, showing it
1963 @cindex Texinfo file section structure, showing it
1964
1965 You can show the section structure of a Texinfo file by using the
1966 @kbd{C-c C-s} command (@code{texinfo-show-structure}). This command
1967 shows the section structure of a Texinfo file by listing the lines
1968 that begin with the @@-commands for @code{@@chapter},
1969 @code{@@section}, and the like. It constructs what amounts
1970 to a table of contents. These lines are displayed in another buffer
1971 called the @samp{*Occur*} buffer. In that buffer, you can position
1972 the cursor over one of the lines and use the @kbd{C-c C-c} command
1973 (@code{occur-mode-goto-occurrence}), to jump to the corresponding spot
1974 in the Texinfo file.@refill
1975
1976 @table @kbd
1977 @item C-c C-s
1978 @itemx M-x texinfo-show-structure
1979 @findex texinfo-show-structure
1980 Show the @code{@@chapter}, @code{@@section}, and such lines of a
1981 Texinfo file.@refill
1982
1983 @item C-c C-c
1984 @itemx M-x occur-mode-goto-occurrence
1985 @findex occur-mode-goto-occurrence
1986 Go to the line in the Texinfo file corresponding to the line under the
1987 cursor in the @file{*Occur*} buffer.@refill
1988 @end table
1989
1990 If you call @code{texinfo-show-structure} with a prefix argument by
1991 typing @w{@kbd{C-u C-c C-s}}, it will list not only those lines with the
1992 @@-commands for @code{@@chapter}, @code{@@section}, and the like, but
1993 also the @code{@@node} lines. You can use @code{texinfo-show-structure}
1994 with a prefix argument to check whether the `Next', `Previous', and `Up'
1995 pointers of an @code{@@node} line are correct.
1996
1997 Often, when you are working on a manual, you will be interested only
1998 in the structure of the current chapter. In this case, you can mark
1999 off the region of the buffer that you are interested in by using the
2000 @kbd{C-x n n} (@code{narrow-to-region}) command and
2001 @code{texinfo-show-structure} will work on only that region. To see
2002 the whole buffer again, use @w{@kbd{C-x n w}} (@code{widen}).
2003 (@xref{Narrowing, , , xemacs, XEmacs User's Manual}, for more
2004 information about the narrowing commands.)@refill
2005
2006 @vindex page-delimiter
2007 @cindex Page delimiter in Texinfo mode
2008 In addition to providing the @code{texinfo-show-structure} command,
2009 Texinfo mode sets the value of the page delimiter variable to match
2010 the chapter-level @@-commands. This enables you to use the @kbd{C-x
2011 ]} (@code{forward-page}) and @kbd{C-x [} (@code{backward-page})
2012 commands to move forward and backward by chapter, and to use the
2013 @kbd{C-x n p} (@code{narrow-to-page}) command to narrow to a chapter.
2014 @xref{Pages, , , xemacs, XEmacs User's Manual}, for more information
2015 about the page commands.@refill
2016
2017 @node Updating Nodes and Menus
2018 @comment node-name, next, previous, up
2019 @section Updating Nodes and Menus
2020 @cindex Updating nodes and menus
2021 @cindex Create nodes, menus automatically
2022 @cindex Insert nodes, menus automatically
2023 @cindex Automatically insert nodes, menus
2024
2025 Texinfo mode provides commands for automatically creating or updating
2026 menus and node pointers. The commands are called ``update'' commands
2027 because their most frequent use is for updating a Texinfo file after you
2028 have worked on it; but you can use them to insert the `Next',
2029 `Previous', and `Up' pointers into an @code{@@node} line that has none
2030 and to create menus in a file that has none.
2031
2032 If you do not use the updating commands, you need to write menus and
2033 node pointers by hand, which is a tedious task.@refill
2034
2035 @menu
2036 * Updating Commands:: Five major updating commands.
2037 * Updating Requirements:: How to structure a Texinfo file for
2038 using the updating command.
2039 * Other Updating Commands:: How to indent descriptions, insert
2040 missing nodes lines, and update
2041 nodes in sequence.
2042 @end menu
2043
2044 @node Updating Commands
2045 @subsection The Updating Commands
2046
2047 You can use the updating commands to:@refill
2048
2049 @itemize @bullet
2050 @item
2051 insert or update the `Next', `Previous', and `Up' pointers of a
2052 node,@refill
2053
2054 @item
2055 insert or update the menu for a section, and@refill
2056
2057 @item
2058 create a master menu for a Texinfo source file.@refill
2059 @end itemize
2060
2061 You can also use the commands to update all the nodes and menus in a
2062 region or in a whole Texinfo file.@refill
2063
2064 The updating commands work only with conventional Texinfo files, which
2065 are structured hierarchically like books. In such files, a structuring
2066 command line must follow closely after each @code{@@node} line, except
2067 for the `Top' @code{@@node} line. (A @dfn{structuring command line} is
2068 a line beginning with @code{@@chapter}, @code{@@section}, or other
2069 similar command.)
2070
2071 You can write the structuring command line on the line that follows
2072 immediately after an @code{@@node} line or else on the line that
2073 follows after a single @code{@@comment} line or a single
2074 @code{@@ifinfo} line. You cannot interpose more than one line between
2075 the @code{@@node} line and the structuring command line; and you may
2076 interpose only an @code{@@comment} line or an @code{@@ifinfo} line.
2077
2078 Commands which work on a whole buffer require that the `Top' node be
2079 followed by a node with an @code{@@chapter} or equivalent-level command.
2080 The menu updating commands will not create a main or master menu for a
2081 Texinfo file that has only @code{@@chapter}-level nodes! The menu
2082 updating commands only create menus @emph{within} nodes for lower level
2083 nodes. To create a menu of chapters, you must provide a `Top'
2084 node.
2085
2086 The menu updating commands remove menu entries that refer to other Info
2087 files since they do not refer to nodes within the current buffer. This
2088 is a deficiency. Rather than use menu entries, you can use cross
2089 references to refer to other Info files. None of the updating commands
2090 affect cross references.@refill
2091
2092 Texinfo mode has five updating commands that are used most often: two
2093 are for updating the node pointers or menu of a single node (or a
2094 region); two are for updating every node pointer and menu in a file;
2095 and one, the @code{texinfo-master-menu} command, is for creating a
2096 master menu for a complete file, and optionally, for updating every
2097 node and menu in the whole Texinfo file.@refill
2098
2099 The @code{texinfo-master-menu} command is the primary command:@refill
2100
2101 @table @kbd
2102 @item C-c C-u m
2103 @itemx M-x texinfo-master-menu
2104 @findex texinfo-master-menu
2105 Create or update a master menu that includes all the other menus
2106 (incorporating the descriptions from pre-existing menus, if
2107 any).@refill
2108
2109 With an argument (prefix argument, @kbd{C-u,} if interactive), first create or
2110 update all the nodes and all the regular menus in the buffer before
2111 constructing the master menu. (@xref{The Top Node, , The Top Node and
2112 Master Menu}, for more about a master menu.)@refill
2113
2114 For @code{texinfo-master-menu} to work, the Texinfo file must have a
2115 `Top' node and at least one subsequent node.@refill
2116
2117 After extensively editing a Texinfo file, you can type the following:
2118
2119 @example
2120 C-u M-x texinfo-master-menu
2121 @exdent or
2122 C-u C-c C-u m
2123 @end example
2124
2125 @noindent
2126 This updates all the nodes and menus completely and all at once.@refill
2127 @end table
2128
2129 The other major updating commands do smaller jobs and are designed for
2130 the person who updates nodes and menus as he or she writes a Texinfo
2131 file.@refill
2132
2133 @need 1000
2134 The commands are:@refill
2135
2136 @table @kbd
2137 @item C-c C-u C-n
2138 @itemx M-x texinfo-update-node
2139 @findex texinfo-update-node
2140 Insert the `Next', `Previous', and `Up' pointers for the node that point is
2141 within (i.e., for the @code{@@node} line preceding point). If the
2142 @code{@@node} line has pre-existing `Next', `Previous', or `Up'
2143 pointers in it, the old pointers are removed and new ones inserted.
2144 With an argument (prefix argument, @kbd{C-u}, if interactive), this command
2145 updates all @code{@@node} lines in the region (which is the text
2146 between point and mark).@refill
2147
2148 @item C-c C-u C-m
2149 @itemx M-x texinfo-make-menu
2150 @findex texinfo-make-menu
2151 Create or update the menu in the node that point is within.
2152 With an argument (@kbd{C-u} as prefix argument, if
2153 interactive), the command makes or updates menus for the
2154 nodes which are either within or a part of the
2155 region.@refill
2156
2157 Whenever @code{texinfo-make-menu} updates an existing menu, the
2158 descriptions from that menu are incorporated into the new menu. This
2159 is done by copying descriptions from the existing menu to the entries
2160 in the new menu that have the same node names. If the node names are
2161 different, the descriptions are not copied to the new menu.@refill
2162
2163 @item C-c C-u C-e
2164 @itemx M-x texinfo-every-node-update
2165 @findex texinfo-every-node-update
2166 Insert or update the `Next', `Previous', and `Up' pointers for every
2167 node in the buffer.@refill
2168
2169 @item C-c C-u C-a
2170 @itemx M-x texinfo-all-menus-update
2171 @findex texinfo-all-menus-update
2172 Create or update all the menus in the buffer. With an argument
2173 (@kbd{C-u} as prefix argument, if interactive), first insert
2174 or update all the node
2175 pointers before working on the menus.@refill
2176
2177 If a master menu exists, the @code{texinfo-all-menus-update} command
2178 updates it; but the command does not create a new master menu if none
2179 already exists. (Use the @code{texinfo-master-menu} command for
2180 that.)@refill
2181
2182 When working on a document that does not merit a master menu, you can
2183 type the following:
2184
2185 @example
2186 C-u C-c C-u C-a
2187 @exdent or
2188 C-u M-x texinfo-all-menus-update
2189 @end example
2190
2191 @noindent
2192 This updates all the nodes and menus.@refill
2193 @end table
2194
2195 The @code{texinfo-column-for-description} variable specifies the
2196 column to which menu descriptions are indented. By default, the value
2197 is 32 although it can be useful to reduce it to as low as 24. You
2198 can set the variable via customization (@pxref{Changing an Option,,,
2199 xemacs, XEmacs User's Manual}) or with the @kbd{M-x set-variable}
2200 command (@pxref{Examining, , Examining and Setting Variables, xemacs,
2201 XEmacs User's Manual}).
2202
2203 Also, the @code{texinfo-indent-menu-description} command may be used to
2204 indent existing menu descriptions to a specified column. Finally, if
2205 you wish, you can use the @code{texinfo-insert-node-lines} command to
2206 insert missing @code{@@node} lines into a file. (@xref{Other Updating
2207 Commands}, for more information.)@refill
2208
2209 @node Updating Requirements
2210 @subsection Updating Requirements
2211 @cindex Updating requirements
2212 @cindex Requirements for updating commands
2213
2214 To use the updating commands, you must organize the Texinfo file
2215 hierarchically with chapters, sections, subsections, and the like.
2216 When you construct the hierarchy of the manual, do not `jump down'
2217 more than one level at a time: you can follow the `Top' node with a
2218 chapter, but not with a section; you can follow a chapter with a
2219 section, but not with a subsection. However, you may `jump up' any
2220 number of levels at one time---for example, from a subsection to a
2221 chapter.@refill
2222
2223 Each @code{@@node} line, with the exception of the line for the `Top'
2224 node, must be followed by a line with a structuring command such as
2225 @code{@@chapter}, @code{@@section}, or
2226 @code{@@unnumberedsubsec}.@refill
2227
2228 Each @code{@@node} line/structuring-command line combination
2229 must look either like this:
2230
2231 @example
2232 @group
2233 @@node Comments, Minimum, Conventions, Overview
2234 @@comment node-name, next, previous, up
2235 @@section Comments
2236 @end group
2237 @end example
2238
2239 or like this (without the @code{@@comment} line):
2240
2241 @example
2242 @group
2243 @@node Comments, Minimum, Conventions, Overview
2244 @@section Comments
2245 @end group
2246 @end example
2247
2248 or like this (without the explicit node pointers):
2249
2250 @example
2251 @group
2252 @@node Comments
2253 @@section Comments
2254 @end group
2255 @end example
2256
2257 @noindent
2258 In this example, `Comments' is the name of both the node and the
2259 section. The next node is called `Minimum' and the previous node is
2260 called `Conventions'. The `Comments' section is within the `Overview'
2261 node, which is specified by the `Up' pointer. (Instead of an
2262 @code{@@comment} line, you may also write an @code{@@ifinfo} line.)
2263
2264 If a file has a `Top' node, it must be called @samp{top} or @samp{Top}
2265 and be the first node in the file.
2266
2267 The menu updating commands create a menu of sections within a chapter,
2268 a menu of subsections within a section, and so on. This means that
2269 you must have a `Top' node if you want a menu of chapters.@refill
2270
2271 Incidentally, the @code{makeinfo} command will create an Info file for a
2272 hierarchically organized Texinfo file that lacks `Next', `Previous' and
2273 `Up' pointers. Thus, if you can be sure that your Texinfo file will be
2274 formatted with @code{makeinfo}, you have no need for the update node
2275 commands. (@xref{Creating an Info File}, for more information about
2276 @code{makeinfo}.) However, both @code{makeinfo} and the
2277 @code{texinfo-format-@dots{}} commands require that you insert menus in
2278 the file.
2279
2280
2281 @node Other Updating Commands
2282 @subsection Other Updating Commands
2283
2284 In addition to the five major updating commands, Texinfo mode
2285 possesses several less frequently used updating commands:@refill
2286
2287 @table @kbd
2288 @item M-x texinfo-insert-node-lines
2289 @findex texinfo-insert-node-lines
2290 Insert @code{@@node} lines before the @code{@@chapter},
2291 @code{@@section}, and other sectioning commands wherever they are
2292 missing throughout a region in a Texinfo file.@refill
2293
2294 With an argument (@kbd{C-u} as prefix argument, if interactive), the
2295 @code{texinfo-insert-node-lines} command not only inserts
2296 @code{@@node} lines but also inserts the chapter or section titles as
2297 the names of the corresponding nodes. In addition, it inserts the
2298 titles as node names in pre-existing @code{@@node} lines that lack
2299 names. Since node names should be more concise than section or
2300 chapter titles, you must manually edit node names so inserted.@refill
2301
2302 For example, the following marks a whole buffer as a region and inserts
2303 @code{@@node} lines and titles throughout:@refill
2304
2305 @example
2306 C-x h C-u M-x texinfo-insert-node-lines
2307 @end example
2308
2309 This command inserts titles as node names in @code{@@node} lines; the
2310 @code{texinfo-start-menu-description} command (@pxref{Inserting,
2311 Inserting Frequently Used Commands}) inserts titles as descriptions in
2312 menu entries, a different action. However, in both cases, you need to
2313 edit the inserted text.
2314
2315 @item M-x texinfo-multiple-files-update
2316 @findex texinfo-multiple-files-update @r{(in brief)}
2317 Update nodes and menus in a document built from several separate files.
2318 With @kbd{C-u} as a prefix argument, create and insert a master menu in
2319 the outer file. With a numeric prefix argument, such as @kbd{C-u 2}, first
2320 update all the menus and all the `Next', `Previous', and `Up' pointers
2321 of all the included files before creating and inserting a master menu in
2322 the outer file. The @code{texinfo-multiple-files-update} command is
2323 described in the appendix on @code{@@include} files.
2324 @xref{texinfo-multiple-files-update}.
2325
2326 @item M-x texinfo-indent-menu-description
2327 @findex texinfo-indent-menu-description
2328 Indent every description in the menu following point to the specified
2329 column. You can use this command to give yourself more space for
2330 descriptions. With an argument (@kbd{C-u} as prefix argument, if
2331 interactive), the @code{texinfo-indent-menu-description} command indents
2332 every description in every menu in the region. However, this command
2333 does not indent the second and subsequent lines of a multi-line
2334 description.@refill
2335
2336 @item M-x texinfo-sequential-node-update
2337 @findex texinfo-sequential-node-update
2338 Insert the names of the nodes immediately following and preceding the
2339 current node as the `Next' or `Previous' pointers regardless of those
2340 nodes' hierarchical level. This means that the `Next' node of a
2341 subsection may well be the next chapter. Sequentially ordered nodes are
2342 useful for novels and other documents that you read through
2343 sequentially. (However, in Info, the @kbd{g *} command lets
2344 you look through the file sequentially, so sequentially ordered nodes
2345 are not strictly necessary.) With an argument (prefix argument, if
2346 interactive), the @code{texinfo-sequential-node-update} command
2347 sequentially updates all the nodes in the region.@refill
2348 @end table
2349
2350 @node Info Formatting
2351 @comment node-name, next, previous, up
2352 @section Formatting for Info
2353 @cindex Formatting for Info
2354 @cindex Running an Info formatter
2355 @cindex Info formatting
2356
2357 Texinfo mode provides several commands for formatting part or all of a
2358 Texinfo file for Info. Often, when you are writing a document, you
2359 want to format only part of a file---that is, a region.@refill
2360
2361 You can use either the @code{texinfo-format-region} or the
2362 @code{makeinfo-region} command to format a region:@refill
2363
2364 @table @kbd
2365 @findex texinfo-format-region
2366 @item C-c C-e C-r
2367 @itemx M-x texinfo-format-region
2368 @itemx C-c C-m C-r
2369 @itemx M-x makeinfo-region
2370 Format the current region for Info.@refill
2371 @end table
2372
2373 You can use either the @code{texinfo-format-buffer} or the
2374 @code{makeinfo-buffer} command to format a whole buffer:@refill
2375
2376 @table @kbd
2377 @findex texinfo-format-buffer
2378 @item C-c C-e C-b
2379 @itemx M-x texinfo-format-buffer
2380 @itemx C-c C-m C-b
2381 @itemx M-x makeinfo-buffer
2382 Format the current buffer for Info.@refill
2383 @end table
2384
2385 @need 1000
2386 For example, after writing a Texinfo file, you can type the following:
2387
2388 @example
2389 C-u C-c C-u m
2390 @exdent or
2391 C-u M-x texinfo-master-menu
2392 @end example
2393
2394 @noindent
2395 This updates all the nodes and menus. Then type the following to create
2396 an Info file:
2397
2398 @example
2399 C-c C-m C-b
2400 @exdent or
2401 M-x makeinfo-buffer
2402 @end example
2403
2404 For @TeX{} or the Info formatting commands to work, the file @emph{must}
2405 include a line that has @code{@@setfilename} in its header.
2406
2407 @xref{Creating an Info File}, for details about Info formatting.@refill
2408
2409 @node Printing
2410 @comment node-name, next, previous, up
2411 @section Printing
2412 @cindex Formatting for printing
2413 @cindex Printing a region or buffer
2414 @cindex Region formatting and printing
2415 @cindex Buffer formatting and printing
2416 @cindex Part of file formatting and printing
2417
2418 Typesetting and printing a Texinfo file is a multi-step process in which
2419 you first create a file for printing (called a DVI file), and then
2420 print the file. Optionally, you may also create indices. To do this,
2421 you must run the @code{texindex} command after first running the
2422 @code{tex} typesetting command; and then you must run the @code{tex}
2423 command again. Or else run the @code{texi2dvi} command which
2424 automatically creates indices as needed (@pxref{Format with texi2dvi}).
2425
2426 Often, when you are writing a document, you want to typeset and print
2427 only part of a file to see what it will look like. You can use the
2428 @code{texinfo-tex-region} and related commands for this purpose. Use
2429 the @code{texinfo-tex-buffer} command to format all of a
2430 buffer.@refill
2431
2432 @table @kbd
2433 @item C-c C-t C-b
2434 @itemx M-x texinfo-tex-buffer
2435 @findex texinfo-tex-buffer
2436 Run @code{texi2dvi} on the buffer. In addition to running @TeX{} on the
2437 buffer, this command automatically creates or updates indices as
2438 needed.@refill
2439
2440 @item C-c C-t C-r
2441 @itemx M-x texinfo-tex-region
2442 @findex texinfo-tex-region
2443 Run @TeX{} on the region.@refill
2444
2445 @item C-c C-t C-i
2446 @itemx M-x texinfo-texindex
2447 Run @code{texindex} to sort the indices of a Texinfo file formatted with
2448 @code{texinfo-tex-region}. The @code{texinfo-tex-region} command does
2449 not run @code{texindex} automatically; it only runs the @code{tex}
2450 typesetting command. You must run the @code{texinfo-tex-region} command
2451 a second time after sorting the raw index files with the @code{texindex}
2452 command. (Usually, you do not format an index when you format a region,
2453 only when you format a buffer. Now that the @code{texi2dvi} command
2454 exists, there is little or no need for this command.)@refill
2455
2456 @item C-c C-t C-p
2457 @itemx M-x texinfo-tex-print
2458 @findex texinfo-tex-print
2459 Print the file (or the part of the file) previously formatted with
2460 @code{texinfo-tex-buffer} or @code{texinfo-tex-region}.@refill
2461 @end table
2462
2463 For @code{texinfo-tex-region} or @code{texinfo-tex-buffer} to work, the
2464 file @emph{must} start with a @samp{\input texinfo} line and must
2465 include an @code{@@settitle} line. The file must end with @code{@@bye}
2466 on a line by itself. (When you use @code{texinfo-tex-region}, you must
2467 surround the @code{@@settitle} line with start-of-header and
2468 end-of-header lines.)@refill
2469
2470 @xref{Hardcopy}, for a description of the other @TeX{} related
2471 commands, such as @code{tex-show-print-queue}.@refill
2472
2473 @node Texinfo Mode Summary
2474 @comment node-name, next, previous, up
2475 @section Texinfo Mode Summary
2476
2477 In Texinfo mode, each set of commands has default keybindings that
2478 begin with the same keys. All the commands that are custom-created
2479 for Texinfo mode begin with @kbd{C-c}. The keys are somewhat
2480 mnemonic.@refill
2481
2482 @subheading Insert Commands
2483
2484 The insert commands are invoked by typing @kbd{C-c} twice and then the
2485 first letter of the @@-command to be inserted. (It might make more
2486 sense mnemonically to use @kbd{C-c C-i}, for `custom insert', but
2487 @kbd{C-c C-c} is quick to type.)@refill
2488
2489 @example
2490 C-c C-c c @r{Insert} @samp{@@code}.
2491 C-c C-c d @r{Insert} @samp{@@dfn}.
2492 C-c C-c e @r{Insert} @samp{@@end}.
2493 C-c C-c i @r{Insert} @samp{@@item}.
2494 C-c C-c n @r{Insert} @samp{@@node}.
2495 C-c C-c s @r{Insert} @samp{@@samp}.
2496 C-c C-c v @r{Insert} @samp{@@var}.
2497 C-c @{ @r{Insert braces.}
2498 C-c ]
2499 C-c @} @r{Move out of enclosing braces.}
2500
2501 @group
2502 C-c C-c C-d @r{Insert a node's section title}
2503 @r{in the space for the description}
2504 @r{in a menu entry line.}
2505 @end group
2506 @end example
2507
2508 @subheading Show Structure
2509
2510 The @code{texinfo-show-structure} command is often used within a
2511 narrowed region.@refill
2512
2513 @example
2514 C-c C-s @r{List all the headings.}
2515 @end example
2516
2517 @subheading The Master Update Command
2518
2519 The @code{texinfo-master-menu} command creates a master menu; and can
2520 be used to update every node and menu in a file as well.@refill
2521
2522 @c Probably should use @tables in this section.
2523 @example
2524 @group
2525 C-c C-u m
2526 M-x texinfo-master-menu
2527 @r{Create or update a master menu.}
2528 @end group
2529
2530 @group
2531 C-u C-c C-u m @r{With @kbd{C-u} as a prefix argument, first}
2532 @r{create or update all nodes and regular}
2533 @r{menus, and then create a master menu.}
2534 @end group
2535 @end example
2536
2537 @subheading Update Pointers
2538
2539 The update pointer commands are invoked by typing @kbd{C-c C-u} and
2540 then either @kbd{C-n} for @code{texinfo-update-node} or @kbd{C-e} for
2541 @code{texinfo-every-node-update}.@refill
2542
2543 @example
2544 C-c C-u C-n @r{Update a node.}
2545 C-c C-u C-e @r{Update every node in the buffer.}
2546 @end example
2547
2548 @subheading Update Menus
2549
2550 Invoke the update menu commands by typing @kbd{C-c C-u}
2551 and then either @kbd{C-m} for @code{texinfo-make-menu} or
2552 @kbd{C-a} for @code{texinfo-all-menus-update}. To update
2553 both nodes and menus at the same time, precede @kbd{C-c C-u
2554 C-a} with @kbd{C-u}.@refill
2555
2556 @example
2557 C-c C-u C-m @r{Make or update a menu.}
2558
2559 @group
2560 C-c C-u C-a @r{Make or update all}
2561 @r{menus in a buffer.}
2562 @end group
2563
2564 @group
2565 C-u C-c C-u C-a @r{With @kbd{C-u} as a prefix argument,}
2566 @r{first create or update all nodes and}
2567 @r{then create or update all menus.}
2568 @end group
2569 @end example
2570
2571 @subheading Format for Info
2572
2573 The Info formatting commands that are written in XEmacs Lisp are
2574 invoked by typing @kbd{C-c C-e} and then either @kbd{C-r} for a region
2575 or @kbd{C-b} for the whole buffer.@refill
2576
2577 The Info formatting commands that are written in C and based on the
2578 @code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
2579 either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.@refill
2580
2581 @need 800
2582 @noindent
2583 Use the @code{texinfo-format@dots{}} commands:
2584
2585 @example
2586 @group
2587 C-c C-e C-r @r{Format the region.}
2588 C-c C-e C-b @r{Format the buffer.}
2589 @end group
2590 @end example
2591
2592 @need 750
2593 @noindent
2594 Use @code{makeinfo}:
2595
2596 @example
2597 C-c C-m C-r @r{Format the region.}
2598 C-c C-m C-b @r{Format the buffer.}
2599 C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
2600 C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
2601 @end example
2602
2603 @subheading Typeset and Print
2604
2605 The @TeX{} typesetting and printing commands are invoked by typing
2606 @kbd{C-c C-t} and then another control command: @kbd{C-r} for
2607 @code{texinfo-tex-region}, @kbd{C-b} for @code{texinfo-tex-buffer},
2608 and so on.@refill
2609
2610 @example
2611 C-c C-t C-r @r{Run @TeX{} on the region.}
2612 C-c C-t C-b @r{Run} @code{texi2dvi} @r{on the buffer.}
2613 C-c C-t C-i @r{Run} @code{texindex}.
2614 C-c C-t C-p @r{Print the DVI file.}
2615 C-c C-t C-q @r{Show the print queue.}
2616 C-c C-t C-d @r{Delete a job from the print queue.}
2617 C-c C-t C-k @r{Kill the current @TeX{} formatting job.}
2618 C-c C-t C-x @r{Quit a currently stopped @TeX{} formatting job.}
2619 C-c C-t C-l @r{Recenter the output buffer.}
2620 @end example
2621
2622 @subheading Other Updating Commands
2623
2624 The remaining updating commands do not have standard keybindings because
2625 they are rarely used.
2626
2627 @example
2628 @group
2629 M-x texinfo-insert-node-lines
2630 @r{Insert missing @code{@@node} lines in region.}
2631 @r{With @kbd{C-u} as a prefix argument,}
2632 @r{use section titles as node names.}
2633 @end group
2634
2635 @group
2636 M-x texinfo-multiple-files-update
2637 @r{Update a multi-file document.}
2638 @r{With @kbd{C-u 2} as a prefix argument,}
2639 @r{create or update all nodes and menus}
2640 @r{in all included files first.}
2641 @end group
2642
2643 @group
2644 M-x texinfo-indent-menu-description
2645 @r{Indent descriptions.}
2646 @end group
2647
2648 @group
2649 M-x texinfo-sequential-node-update
2650 @r{Insert node pointers in strict sequence.}
2651 @end group
2652 @end example
2653
2654
2655 @node Beginning a File
2656 @chapter Beginning a Texinfo File
2657 @cindex Beginning a Texinfo file
2658 @cindex Texinfo file beginning
2659 @cindex File beginning
2660
2661 Certain pieces of information must be provided at the beginning of a
2662 Texinfo file, such as the name for the output file(s), the title of the
2663 document, and the Top node. A table of contents is also generally
2664 produced here.
2665
2666 This chapter expands on the minimal complete Texinfo source file
2667 previously given (@pxref{Six Parts}). It describes the numerous
2668 commands for handling the traditional frontmatter items in Texinfo.
2669
2670 @cindex Frontmatter, text in
2671 Straight text outside of any command before the Top node should be
2672 avoided. Such text is treated differently in the different output
2673 formats: visible in @TeX{} and HTML, by default not shown in Info
2674 readers, and so on.
2675
2676 @menu
2677 * Sample Beginning:: A sample beginning for a Texinfo file.
2678 * Texinfo File Header:: The first lines.
2679 * Document Permissions:: Ensuring your manual is free.
2680 * Titlepage & Copyright Page:: Creating the title and copyright pages.
2681 * Contents:: How to create a table of contents.
2682 * The Top Node:: Creating the `Top' node and master menu.
2683 * Global Document Commands:: Affecting formatting throughout.
2684 * Software Copying Permissions:: Ensure that you and others continue to
2685 have the right to use and share software.
2686 @end menu
2687
2688
2689 @node Sample Beginning
2690 @section Sample Texinfo File Beginning
2691
2692 @cindex Example beginning of Texinfo file
2693
2694 The following sample shows what is needed. The elements given here are
2695 explained in more detail in the following sections. Other commands are
2696 often included at the beginning of Texinfo files, but the ones here are
2697 the most critical.
2698
2699 @xref{GNU Sample Texts}, for the full texts to be used in GNU manuals.
2700
2701 @example
2702 \input texinfo @@c -*-texinfo-*-
2703 @@c %**start of header
2704 @@setfilename @var{infoname}.info
2705 @@settitle @var{name-of-manual} @var{version}
2706 @@c %**end of header
2707
2708 @@copying
2709 This manual is for @var{program}, version @var{version}.
2710
2711 Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
2712
2713 @group
2714 @@quotation
2715 Permission is granted to @dots{}
2716 @@end quotation
2717 @@end copying
2718 @end group
2719
2720 @group
2721 @@titlepage
2722 @@title @var{name-of-manual-when-printed}
2723 @@subtitle @var{subtitle-if-any}
2724 @@subtitle @var{second-subtitle}
2725 @@author @var{author}
2726 @end group
2727
2728 @group
2729 @@c The following two commands
2730 @@c start the copyright page.
2731 @@page
2732 @@vskip 0pt plus 1filll
2733 @@insertcopying
2734 @end group
2735
2736 Published by @dots{}
2737 @@end titlepage
2738
2739 @@c So the toc is printed at the start.
2740 @@contents
2741
2742 @@ifnottex
2743 @@node Top
2744 @@top @var{title}
2745
2746 This manual is for @var{program}, version @var{version}.
2747 @@end ifnottex
2748
2749 @group
2750 @@menu
2751 * First Chapter:: Getting started @dots{}
2752 * Second Chapter:: @dots{}
2753 @dots{}
2754 * Copying:: Your rights and freedoms.
2755 @@end menu
2756 @end group
2757
2758 @group
2759 @@node First Chapter
2760 @@chapter First Chapter
2761
2762 @@cindex first chapter
2763 @@cindex chapter, first
2764 @dots{}
2765 @end group
2766 @end example
2767
2768
2769 @node Texinfo File Header
2770 @section Texinfo File Header
2771 @cindex Header for Texinfo files
2772 @cindex Texinfo file header
2773
2774 Texinfo files start with at least three lines that provide Info and
2775 @TeX{} with necessary information. These are the @code{\input texinfo}
2776 line, the @code{@@settitle} line, and the @code{@@setfilename} line.
2777
2778 Also, if you want to format just part of the Texinfo file, you must
2779 write the @code{@@settitle} and @code{@@setfilename} lines between
2780 start-of-header and end-of-header lines. The start- and end-of-header
2781 lines are optional, but they do no harm, so you might as well always
2782 include them.
2783
2784 Any command that affects document formatting as a whole makes sense to
2785 include in the header. @code{@@synindex} (@pxref{synindex}), for
2786 instance, is another command often included in the header. @xref{GNU
2787 Sample Texts}, for complete sample texts.
2788
2789 Thus, the beginning of a Texinfo file generally looks like this:
2790
2791 @example
2792 @group
2793 \input texinfo @@c -*-texinfo-*-
2794 @@c %**start of header
2795 @@setfilename sample.info
2796 @@settitle Sample Manual 1.0
2797 @@c %**end of header
2798 @end group
2799 @end example
2800
2801 @menu
2802 * First Line:: The first line of a Texinfo file.
2803 * Start of Header:: Formatting a region requires this.
2804 * setfilename:: Tell Info the name of the Info file.
2805 * settitle:: Create a title for the printed work.
2806 * End of Header:: Formatting a region requires this.
2807 @end menu
2808
2809
2810 @node First Line
2811 @subsection The First Line of a Texinfo File
2812 @cindex First line of a Texinfo file
2813 @cindex Beginning line of a Texinfo file
2814 @cindex Header of a Texinfo file
2815
2816 Every Texinfo file that is to be the top-level input to @TeX{} must begin
2817 with a line that looks like this:
2818
2819 @example
2820 \input texinfo @@c -*-texinfo-*-
2821 @end example
2822
2823 @noindent
2824 This line serves two functions:
2825
2826 @enumerate
2827 @item
2828 When the file is processed by @TeX{}, the @samp{\input texinfo} command
2829 tells @TeX{} to load the macros needed for processing a Texinfo file.
2830 These are in a file called @file{texinfo.tex}, which should have been
2831 installed on your system along with either the @TeX{} or Texinfo
2832 software. @TeX{} uses the backslash, @samp{\}, to mark the beginning of
2833 a command, exactly as Texinfo uses @samp{@@}. The @file{texinfo.tex}
2834 file causes the switch from @samp{\} to @samp{@@}; before the switch
2835 occurs, @TeX{} requires @samp{\}, which is why it appears at the
2836 beginning of the file.
2837
2838 @item
2839 When the file is edited in XEmacs, the @samp{-*-texinfo-*-} mode
2840 specification tells XEmacs to use Texinfo mode.
2841 @end enumerate
2842
2843
2844 @node Start of Header
2845 @subsection Start of Header
2846 @cindex Start of header line
2847
2848 A start-of-header line is a Texinfo comment that looks like this:
2849
2850 @example
2851 @@c %**start of header
2852 @end example
2853
2854 Write the start-of-header line on the second line of a Texinfo file.
2855 Follow the start-of-header line with @code{@@setfilename} and
2856 @code{@@settitle} lines and, optionally, with other commands that
2857 globally affect the document formatting, such as @code{@@synindex} or
2858 @code{@@footnotestyle}; and then by an end-of-header line (@pxref{End of
2859 Header}).
2860
2861 The start- and end-of-header lines allow you to format only part of a
2862 Texinfo file for Info or printing. @xref{texinfo-format commands}.
2863
2864 The odd string of characters, @samp{%**}, is to ensure that no other
2865 comment is accidentally taken for a start-of-header line. You can
2866 change it if you wish by setting the @code{tex-start-of-header} and/or
2867 @code{tex-end-of-header} XEmacs variables. @xref{Texinfo Mode Printing}.
2868
2869
2870 @node setfilename
2871 @subsection @code{@@setfilename}: Set the output file name
2872 @findex setfilename
2873 @cindex Texinfo requires @code{@@setfilename}
2874
2875 In order to serve as the primary input file for either @code{makeinfo}
2876 or @TeX{}, a Texinfo file must contain a line that looks like this:
2877
2878 @example
2879 @@setfilename @var{info-file-name}
2880 @end example
2881
2882 Write the @code{@@setfilename} command at the beginning of a line and
2883 follow it on the same line by the Info file name. Do not write anything
2884 else on the line; anything on the line after the command is considered
2885 part of the file name, including what would otherwise be a
2886 comment.
2887
2888 @cindex Ignored before @code{@@setfilename}
2889 @cindex @samp{\input} source line ignored
2890 The Info formatting commands ignore everything written before the
2891 @code{@@setfilename} line, which is why the very first line of
2892 the file (the @code{\input} line) does not show up in the output.
2893
2894 The @code{@@setfilename} line specifies the name of the output file to
2895 be generated. This name must be different from the name of the Texinfo
2896 file. There are two conventions for choosing the name: you can either
2897 remove the extension (such as @samp{.texi}) entirely from the input file
2898 name, or, preferably, replace it with the @samp{.info} extension.
2899
2900 @cindex Length of file names
2901 @cindex File name collision
2902 @cindex Info file name, choosing
2903 Although an explicit @samp{.info} extension is preferable, some
2904 operating systems cannot handle long file names. You can run into a
2905 problem even when the file name you specify is itself short enough.
2906 This occurs because the Info formatters split a long Info file into
2907 short indirect subfiles, and name them by appending @samp{-1},
2908 @samp{-2}, @dots{}, @samp{-10}, @samp{-11}, and so on, to the original
2909 file name. (@xref{Tag and Split Files}.) The subfile name
2910 @file{texinfo.info-10}, for example, is too long for old systems with a
2911 14-character limit on filenames; so the Info file name for this document
2912 is @file{texinfo} rather than @file{texinfo.info}. When @code{makeinfo}
2913 is running on operating systems such as MS-DOS which impose severe
2914 limits on file names, it may remove some characters from the original
2915 file name to leave enough space for the subfile suffix, thus producing
2916 files named @file{texin-10}, @file{gcc.i12}, etc.
2917
2918 When producing HTML output, @code{makeinfo} will replace any extension
2919 with @samp{html}, or add @samp{.html} if the given name has no
2920 extension.
2921
2922 @pindex texinfo.cnf
2923 The @code{@@setfilename} line produces no output when you typeset a
2924 manual with @TeX{}, but it is nevertheless essential: it opens the
2925 index, cross-reference, and other auxiliary files used by Texinfo, and
2926 also reads @file{texinfo.cnf} if that file is present on your system
2927 (@pxref{Preparing for TeX,, Preparing for @TeX{}}).
2928
2929
2930 @node settitle
2931 @subsection @code{@@settitle}: Set the document title
2932 @findex settitle
2933
2934 In order to be made into a printed manual, a Texinfo file must contain
2935 a line that looks like this:
2936
2937 @example
2938 @@settitle @var{title}
2939 @end example
2940
2941 Write the @code{@@settitle} command at the beginning of a line and
2942 follow it on the same line by the title. This tells @TeX{} the title to
2943 use in a header or footer. Do not write anything else on the line;
2944 anything on the line after the command is considered part of the title,
2945 including what would otherwise be a comment.
2946
2947 The @code{@@settitle} command should precede everything that generates
2948 actual output. The best place for it is right after the
2949 @code{@@setfilename} command (see the previous section).
2950
2951 @cindex <title> HTML tag
2952 In the HTML file produced by @command{makeinfo}, @var{title} serves as
2953 the document @samp{<title>}. It also becomes the default document
2954 description in the @samp{<head>} part (@pxref{documentdescription}).
2955
2956 The title in the @code{@@settitle} command does not affect the title as
2957 it appears on the title page. Thus, the two do not need not match
2958 exactly. A practice we recommend is to include the version or edition
2959 number of the manual in the @code{@@settitle} title; on the title page,
2960 the version number generally appears as a @code{@@subtitle} so it would
2961 be omitted from the @code{@@title}. @xref{titlepage}.
2962
2963 Conventionally, when @TeX{} formats a Texinfo file for double-sided
2964 output, the title is printed in the left-hand (even-numbered) page
2965 headings and the current chapter title is printed in the right-hand
2966 (odd-numbered) page headings. (@TeX{} learns the title of each chapter
2967 from each @code{@@chapter} command.) By default, no page footer is
2968 printed.
2969
2970 Even if you are printing in a single-sided style, @TeX{} looks for an
2971 @code{@@settitle} command line, in case you include the manual title
2972 in the heading.
2973
2974 @TeX{} prints page headings only for that text that comes after the
2975 @code{@@end titlepage} command in the Texinfo file, or that comes
2976 after an @code{@@headings} command that turns on headings.
2977 (@xref{headings on off, , The @code{@@headings} Command}, for more
2978 information.)
2979
2980 You may, if you wish, create your own, customized headings and footings.
2981 @xref{Headings}, for a detailed discussion of this.
2982
2983
2984 @node End of Header
2985 @subsection End of Header
2986 @cindex End of header line
2987
2988 Follow the header lines with an @w{end-of-header} line, which is a
2989 Texinfo comment that looks like this:
2990
2991 @example
2992 @@c %**end of header
2993 @end example
2994
2995 @xref{Start of Header}.
2996
2997
2998 @node Document Permissions
2999 @section Document Permissions
3000 @cindex Document Permissions
3001 @cindex Copying Permissions
3002
3003 The copyright notice and copying permissions for a document need to
3004 appear in several places in the various Texinfo output formats.
3005 Therefore, Texinfo provides a command (@code{@@copying}) to declare
3006 this text once, and another command (@code{@@insertcopying}) to
3007 insert the text at appropriate points.
3008
3009 @menu
3010 * copying:: Declare the document's copying permissions.
3011 * insertcopying:: Where to insert the permissions.
3012 @end menu
3013
3014
3015 @node copying
3016 @subsection @code{@@copying}: Declare Copying Permissions
3017 @findex copying
3018
3019 The @code{@@copying} command should be given very early in the document;
3020 the recommended location is right after the header material
3021 (@pxref{Texinfo File Header}). It conventionally consists of a sentence
3022 or two about what the program is, identification of the documentation
3023 itself, the legal copyright line, and the copying permissions. Here is
3024 a skeletal example:
3025
3026 @example
3027 @@copying
3028 This manual is for @var{program} (version @var{version}, updated
3029 @var{date}), which @dots{}
3030
3031 Copyright @@copyright@{@} @var{years} @var{copyright-owner}.
3032
3033 @@quotation
3034 Permission is granted to @dots{}
3035 @@end quotation
3036 @@end copying
3037 @end example
3038
3039 The @code{@@quotation} has no legal significance; it's there to improve
3040 readability in some contexts.
3041
3042 @xref{GNU Sample Texts}, for the full text to be used in GNU manuals.
3043 @xref{GNU Free Documentation License}, for the license itself under
3044 which GNU and other free manuals are distributed. You need to include
3045 the license as an appendix to your document.
3046
3047 The text of @code{@@copying} is output as a comment at the beginning of
3048 Info, HTML, and XML output files. It is @emph{not} output implicitly in
3049 plain text or @TeX{}; it's up to you to use @code{@@insertcopying} to
3050 emit the copying information. See the next section for details.
3051
3052 @findex copyright
3053 The @code{@@copyright@{@}} command generates a @samp{c} inside a circle
3054 in output formats that support this (print and HTML). In the other
3055 formats (Info and plain text), it generates @samp{(C)}. The copyright
3056 notice itself has the following legally defined sequence:
3057
3058 @example
3059 Copyright @copyright{} @var{years} @var{copyright-owner}.
3060 @end example
3061
3062 @cindex Copyright word, always in English
3063 The word `Copyright' must always be written in English, even if the
3064 document is otherwise written in another language. This is due to
3065 international law.
3066
3067 @cindex Years, in copyright line
3068 The list of years should include all years in which a version was
3069 completed (even if it was released in a subsequent year). Ranges are
3070 not allowed; each year must be written out individually and in full,
3071 separated by commas.
3072
3073 @cindex Copyright holder for FSF works
3074 @cindex Holder of copyright for FSF works
3075 @cindex Owner of copyright for FSF works
3076 The copyright owner (or owners) is whoever holds legal copyright on the
3077 work. In the case of works assigned to the FSF, the owner is `Free
3078 Software Foundation, Inc.'.
3079
3080 The copyright `line' may actually be split across multiple lines, both
3081 in the source document and in the output. This often happens for
3082 documents with a long history, having many different years of
3083 publication. If you do use several lines, do not indent any of them
3084 (or anything else in the @code{@@copying} block) in the source file.
3085
3086 @xref{Copyright Notices,,,maintain,GNU Maintenance Instructions}, for
3087 additional information.
3088
3089
3090 @node insertcopying
3091 @subsection @code{@@insertcopying}: Include Permissions Text
3092 @findex insertcopying
3093 @cindex Copying text, including
3094 @cindex Permissions text, including
3095 @cindex Including permissions text
3096
3097 The @code{@@insertcopying} command is simply written on a line by
3098 itself, like this:
3099
3100 @example
3101 @@insertcopying
3102 @end example
3103
3104 This inserts the text previously defined by @code{@@copying}. To meet
3105 legal requirements, it must be used on the copyright page in the printed
3106 manual (@pxref{Copyright}).
3107
3108 The @code{@@copying} command itself causes the permissions text to
3109 appear in an Info file @emph{before} the first node. The text is also
3110 copied into the beginning of each split Info output file, as is legally
3111 necessary. This location implies a human reading the manual using Info
3112 does @emph{not} see this text (except when using the advanced Info
3113 command @kbd{g *}), but this does not matter for legal purposes,
3114 because the text is present.
3115
3116 Similarly, the @code{@@copying} text is automatically included at the
3117 beginning of each HTML output file, as an HTML comment. Again, this
3118 text is not visible (unless the reader views the HTML source).
3119
3120 The permissions text defined by @code{@@copying} also appears
3121 automatically at the beginning of the XML output file.
3122
3123
3124 @node Titlepage & Copyright Page
3125 @section Title and Copyright Pages
3126
3127 In hard copy output, the manual's name and author are usually printed on
3128 a title page. Copyright information is usually printed on the back of
3129 the title page.
3130
3131 The title and copyright pages appear in the printed manual, but not in
3132 the Info file. Because of this, it is possible to use several slightly
3133 obscure @TeX{} typesetting commands that cannot be used in an Info file.
3134 In addition, this part of the beginning of a Texinfo file contains the
3135 text of the copying permissions that appears in the printed manual.
3136
3137 @cindex Title page, for plain text
3138 @cindex Copyright page, for plain text
3139 You may wish to include titlepage-like information for plain text
3140 output. Simply place any such leading material between
3141 @code{@@ifplaintext} and @code{@@end ifplaintext}; @command{makeinfo}
3142 includes this when writing plain text (@samp{--no-headers}), along with
3143 an @code{@@insertcopying}.
3144
3145 @menu
3146 * titlepage:: Create a title for the printed document.
3147 * titlefont center sp:: The @code{@@titlefont}, @code{@@center},
3148 and @code{@@sp} commands.
3149 * title subtitle author:: The @code{@@title}, @code{@@subtitle},
3150 and @code{@@author} commands.
3151 * Copyright:: How to write the copyright notice and
3152 include copying permissions.
3153 * end titlepage:: Turn on page headings after the title and
3154 copyright pages.
3155 * headings on off:: An option for turning headings on and off
3156 and double or single sided printing.
3157 @end menu
3158
3159
3160 @node titlepage
3161 @subsection @code{@@titlepage}
3162 @cindex Title page
3163 @findex titlepage
3164
3165 Start the material for the title page and following copyright page
3166 with @code{@@titlepage} on a line by itself and end it with
3167 @code{@@end titlepage} on a line by itself.
3168
3169 The @code{@@end titlepage} command starts a new page and turns on page
3170 numbering. (@xref{Headings, , Page Headings}, for details about how to
3171 generate page headings.) All the material that you want to appear on
3172 unnumbered pages should be put between the @code{@@titlepage} and
3173 @code{@@end titlepage} commands. You can force the table of contents to
3174 appear there with the @code{@@setcontentsaftertitlepage} command
3175 (@pxref{Contents}).
3176
3177 @findex page@r{, within @code{@@titlepage}}
3178 By using the @code{@@page} command you can force a page break within the
3179 region delineated by the @code{@@titlepage} and @code{@@end titlepage}
3180 commands and thereby create more than one unnumbered page. This is how
3181 the copyright page is produced. (The @code{@@titlepage} command might
3182 perhaps have been better named the @code{@@titleandadditionalpages}
3183 command, but that would have been rather long!)
3184
3185 When you write a manual about a computer program, you should write the
3186 version of the program to which the manual applies on the title page.
3187 If the manual changes more frequently than the program or is independent
3188 of it, you should also include an edition number@footnote{We have found
3189 that it is helpful to refer to versions of independent manuals as
3190 `editions' and versions of programs as `versions'; otherwise, we find we
3191 are liable to confuse each other in conversation by referring to both
3192 the documentation and the software with the same words.} for the manual.
3193 This helps readers keep track of which manual is for which version of
3194 the program. (The `Top' node should also contain this information; see
3195 @ref{The Top Node}.)
3196
3197 Texinfo provides two main methods for creating a title page. One method
3198 uses the @code{@@titlefont}, @code{@@sp}, and @code{@@center} commands
3199 to generate a title page in which the words on the page are
3200 centered.
3201
3202 The second method uses the @code{@@title}, @code{@@subtitle}, and
3203 @code{@@author} commands to create a title page with black rules under
3204 the title and author lines and the subtitle text set flush to the
3205 right hand side of the page. With this method, you do not specify any
3206 of the actual formatting of the title page. You specify the text
3207 you want, and Texinfo does the formatting.
3208
3209 You may use either method, or you may combine them; see the examples in
3210 the sections below.
3211
3212 @findex shorttitlepage
3213 @cindex Bastard title page
3214 @cindex Title page, bastard
3215 For extremely simple documents, and for the bastard title page in
3216 traditional book frontmatter, Texinfo also provides a command
3217 @code{@@shorttitlepage} which takes the rest of the line as the title.
3218 The argument is typeset on a page by itself and followed by a blank
3219 page.
3220
3221
3222 @node titlefont center sp
3223 @subsection @code{@@titlefont}, @code{@@center}, and @code{@@sp}
3224 @findex titlefont
3225 @findex center
3226 @findex sp @r{(titlepage line spacing)}
3227
3228 You can use the @code{@@titlefont}, @code{@@sp}, and @code{@@center}
3229 commands to create a title page for a printed document. (This is the
3230 first of the two methods for creating a title page in Texinfo.)
3231
3232 Use the @code{@@titlefont} command to select a large font suitable for
3233 the title itself. You can use @code{@@titlefont} more than once if you
3234 have an especially long title.
3235
3236 For HTML output, each @code{@@titlefont} command produces an
3237 @code{<h1>} heading, but the HTML document @code{<title>} is not
3238 affected. For that, you must put an @code{@@settitle} command before
3239 the @code{@@titlefont} command (@pxref{settitle}).
3240
3241 @need 700
3242 For example:
3243
3244 @example
3245 @@titlefont@{Texinfo@}
3246 @end example
3247
3248 Use the @code{@@center} command at the beginning of a line to center
3249 the remaining text on that line. Thus,
3250
3251 @example
3252 @@center @@titlefont@{Texinfo@}
3253 @end example
3254
3255 @noindent
3256 centers the title, which in this example is ``Texinfo'' printed
3257 in the title font.
3258
3259 Use the @code{@@sp} command to insert vertical space. For example:
3260
3261 @example
3262 @@sp 2
3263 @end example
3264
3265 @noindent
3266 This inserts two blank lines on the printed page. (@xref{sp, ,
3267 @code{@@sp}}, for more information about the @code{@@sp}
3268 command.)
3269
3270 A template for this method looks like this:
3271
3272 @example
3273 @group
3274 @@titlepage
3275 @@sp 10
3276 @@center @@titlefont@{@var{name-of-manual-when-printed}@}
3277 @@sp 2
3278 @@center @var{subtitle-if-any}
3279 @@sp 2
3280 @@center @var{author}
3281 @dots{}
3282 @@end titlepage
3283 @end group
3284 @end example
3285
3286 The spacing of the example fits an 8.5 by 11 inch manual.
3287
3288 You can in fact use these commands anywhere, not just on a title page,
3289 but since they are not logical markup commands, we don't recommend
3290 them.
3291
3292 @node title subtitle author
3293 @subsection @code{@@title}, @code{@@subtitle}, and @code{@@author}
3294 @findex title
3295 @findex subtitle
3296 @findex author
3297
3298 You can use the @code{@@title}, @code{@@subtitle}, and @code{@@author}
3299 commands to create a title page in which the vertical and horizontal
3300 spacing is done for you automatically. This contrasts with the method
3301 described in the previous section, in which the @code{@@sp} command is
3302 needed to adjust vertical spacing.
3303
3304 Write the @code{@@title}, @code{@@subtitle}, or @code{@@author}
3305 commands at the beginning of a line followed by the title, subtitle,
3306 or author. These commands are only effective in @TeX{} output; it's
3307 an error to use them anywhere except within @code{@@titlepage}.
3308
3309 The @code{@@title} command produces a line in which the title is set
3310 flush to the left-hand side of the page in a larger than normal font.
3311 The title is underlined with a black rule. Only a single line is
3312 allowed; the @code{@@*} command may not be used to break the title into
3313 two lines. To handle very long titles, you may find it profitable to
3314 use both @code{@@title} and @code{@@titlefont}; see the final example in
3315 this section.
3316
3317 The @code{@@subtitle} command sets subtitles in a normal-sized font
3318 flush to the right-hand side of the page.
3319
3320 The @code{@@author} command sets the names of the author or authors in
3321 a middle-sized font flush to the left-hand side of the page on a line
3322 near the bottom of the title page. The names are underlined with a
3323 black rule that is thinner than the rule that underlines the title.
3324 (The black rule only occurs if the @code{@@author} command line is
3325 followed by an @code{@@page} command line.)
3326
3327 There are two ways to use the @code{@@author} command: you can write
3328 the name or names on the remaining part of the line that starts with
3329 an @code{@@author} command:
3330
3331 @example
3332 @@author by Jane Smith and John Doe
3333 @end example
3334
3335 @noindent
3336 or you can write the names one above each other by using two (or more)
3337 @code{@@author} commands:
3338
3339 @example
3340 @group
3341 @@author Jane Smith
3342 @@author John Doe
3343 @end group
3344 @end example
3345
3346 @noindent
3347 (Only the bottom name is underlined with a black rule.)
3348
3349 @need 950
3350 A template for this method looks like this:
3351
3352 @example
3353 @group
3354 @@titlepage
3355 @@title @var{name-of-manual-when-printed}
3356 @@subtitle @var{subtitle-if-any}
3357 @@subtitle @var{second-subtitle}
3358 @@author @var{author}
3359 @@page
3360 @dots{}
3361 @@end titlepage
3362 @end group
3363 @end example
3364
3365 You may also combine the @code{@@titlefont} method described in the
3366 previous section and @code{@@title} method described in this one. This
3367 may be useful if you have a very long title. Here is a real-life example:
3368
3369 @example
3370 @group
3371 @@titlepage
3372 @@titlefont@{GNU Software@}
3373 @@sp 1
3374 @@title for MS-Windows and MS-DOS
3375 @@subtitle Edition @@value@{e@} for Release @@value@{cde@}
3376 @@author by Daniel Hagerty, Melissa Weisshaus
3377 @@author and Eli Zaretskii
3378 @end group
3379 @end example
3380
3381 @noindent
3382 (The use of @code{@@value} here is explained in @ref{value Example}.
3383
3384
3385 @node Copyright
3386 @subsection Copyright Page
3387 @cindex Copyright page
3388 @cindex Printed permissions
3389 @cindex Permissions, printed
3390
3391 By international treaty, the copyright notice for a book must be either
3392 on the title page or on the back of the title page. When the copyright
3393 notice is on the back of the title page, that page is customarily not
3394 numbered. Therefore, in Texinfo, the information on the copyright page
3395 should be within @code{@@titlepage} and @code{@@end titlepage}
3396 commands.
3397
3398 @findex vskip @r{@TeX{} vertical skip}
3399 @findex filll @r{@TeX{} dimension}
3400 Use the @code{@@page} command to cause a page break. To push the
3401 copyright notice and the other text on the copyright page towards the
3402 bottom of the page, use the following incantation after @code{@@page}:
3403
3404 @example
3405 @@vskip 0pt plus 1filll
3406 @end example
3407
3408 @noindent
3409 This is a @TeX{} command that is not supported by the Info formatting
3410 commands. The @code{@@vskip} command inserts whitespace. The @samp{0pt
3411 plus 1filll} means to put in zero points of mandatory whitespace, and as
3412 much optional whitespace as needed to push the following text to the
3413 bottom of the page. Note the use of three @samp{l}s in the word
3414 @samp{filll}; this is correct.
3415
3416 To insert the copyright text itself, write @code{@@insertcopying}
3417 next (@pxref{Document Permissions}):
3418
3419 @example
3420 @@insertcopying
3421 @end example
3422
3423 Follow the copying text by the publisher, ISBN numbers, cover art
3424 credits, and other such information.
3425
3426 Here is an example putting all this together:
3427
3428 @example
3429 @@titlepage
3430 @dots{}
3431 @@page
3432 @@vskip 0pt plus 1filll
3433 @@insertcopying
3434
3435 Published by @dots{}
3436
3437 Cover art by @dots{}
3438 @@end titlepage
3439 @end example
3440
3441
3442 @node end titlepage
3443 @subsection Heading Generation
3444 @findex end titlepage
3445 @cindex Headings, page, begin to appear
3446 @cindex Titlepage end starts headings
3447 @cindex End titlepage starts headings
3448
3449 Like all @code{@@end} commands (@pxref{Quotations and Examples}), the @code{@@end titlepage} command
3450 must be written at the beginning of a line by itself, with only one
3451 space between the @code{@@end} and the @code{titlepage}. It not only
3452 marks the end of the title and copyright pages, but also causes @TeX{}
3453 to start generating page headings and page numbers.
3454
3455 To repeat what is said elsewhere, Texinfo has two standard page heading
3456 formats, one for documents which are printed on one side of each sheet of paper
3457 (single-sided printing), and the other for documents which are printed on both
3458 sides of each sheet (double-sided printing).
3459 You can specify these formats in different ways:
3460
3461 @itemize @bullet
3462 @item
3463 The conventional way is to write an @code{@@setchapternewpage} command
3464 before the title page commands, and then have the @code{@@end
3465 titlepage} command start generating page headings in the manner desired.
3466 (@xref{setchapternewpage}.)
3467
3468 @item
3469 Alternatively, you can use the @code{@@headings} command to prevent page
3470 headings from being generated or to start them for either single or
3471 double-sided printing. (Write an @code{@@headings} command immediately
3472 after the @code{@@end titlepage} command. @xref{headings on off, , The
3473 @code{@@headings} Command}, for more information.)@refill
3474
3475 @item
3476 Or, you may specify your own page heading and footing format.
3477 @xref{Headings, , Page Headings}, for detailed
3478 information about page headings and footings.
3479 @end itemize
3480
3481 Most documents are formatted with the standard single-sided or
3482 double-sided format, using @code{@@setchapternewpage odd} for
3483 double-sided printing and no @code{@@setchapternewpage} command for
3484 single-sided printing.
3485
3486
3487 @node headings on off
3488 @subsection The @code{@@headings} Command
3489 @findex headings
3490
3491 The @code{@@headings} command is rarely used. It specifies what kind of
3492 page headings and footings to print on each page. Usually, this is
3493 controlled by the @code{@@setchapternewpage} command. You need the
3494 @code{@@headings} command only if the @code{@@setchapternewpage} command
3495 does not do what you want, or if you want to turn off predefined page
3496 headings prior to defining your own. Write an @code{@@headings} command
3497 immediately after the @code{@@end titlepage} command.
3498
3499 You can use @code{@@headings} as follows:
3500
3501 @table @code
3502 @item @@headings off
3503 Turn off printing of page headings.
3504
3505 @item @@headings single
3506 Turn on page headings appropriate for single-sided printing.
3507
3508 @item @@headings double
3509 Turn on page headings appropriate for double-sided printing.
3510
3511 @item @@headings singleafter
3512 @itemx @@headings doubleafter
3513 Turn on @code{single} or @code{double} headings, respectively, after the
3514 current page is output.
3515
3516 @item @@headings on
3517 Turn on page headings: @code{single} if @samp{@@setchapternewpage
3518 on}, @code{double} otherwise.
3519 @end table
3520
3521 For example, suppose you write @code{@@setchapternewpage off} before the
3522 @code{@@titlepage} command to tell @TeX{} to start a new chapter on the
3523 same page as the end of the last chapter. This command also causes
3524 @TeX{} to typeset page headers for single-sided printing. To cause
3525 @TeX{} to typeset for double sided printing, write @code{@@headings
3526 double} after the @code{@@end titlepage} command.
3527
3528 You can stop @TeX{} from generating any page headings at all by
3529 writing @code{@@headings off} on a line of its own immediately after the
3530 line containing the @code{@@end titlepage} command, like this:
3531
3532 @example
3533 @@end titlepage
3534 @@headings off
3535 @end example
3536
3537 @noindent
3538 The @code{@@headings off} command overrides the @code{@@end titlepage}
3539 command, which would otherwise cause @TeX{} to print page headings.
3540
3541 You can also specify your own style of page heading and footing.
3542 @xref{Headings, , Page Headings}, for more information.
3543
3544
3545 @node Contents
3546 @section Generating a Table of Contents
3547 @cindex Table of contents
3548 @cindex Contents, Table of
3549 @cindex Short table of contents
3550 @findex contents
3551 @findex summarycontents
3552 @findex shortcontents
3553
3554 The @code{@@chapter}, @code{@@section}, and other structuring commands
3555 (@pxref{Structuring}) supply the information to make up a
3556 table of contents, but they do not cause an actual table to appear in
3557 the manual. To do this, you must use the @code{@@contents} and/or
3558 @code{@@summarycontents} command(s).
3559
3560 @table @code
3561 @item @@contents
3562 Generates a table of contents in a printed manual, including all
3563 chapters, sections, subsections, etc., as well as appendices and
3564 unnumbered chapters. Headings generated by @code{@@majorheading},
3565 @code{@@chapheading}, and the other @code{@@@dots{}heading} commands
3566 do not appear in the table of contents (@pxref{Structuring Command
3567 Types}).
3568
3569 @item @@shortcontents
3570 @itemx @@summarycontents
3571 (@code{@@summarycontents} is a synonym for @code{@@shortcontents}.)
3572
3573 Generates a short or summary table of contents that lists only the
3574 chapters, appendices, and unnumbered chapters. Sections, subsections
3575 and subsubsections are omitted. Only a long manual needs a short
3576 table of contents in addition to the full table of contents.
3577
3578 @end table
3579
3580 Both contents commands should be written on a line by themselves, and
3581 are best placed near the beginning of the file, after the @code{@@end
3582 titlepage} (@pxref{titlepage}). The contents commands automatically
3583 generate a chapter-like heading at the top of the first table of
3584 contents page, so don't include any sectioning command such as
3585 @code{@@unnumbered} before them.
3586
3587 Since an Info file uses menus instead of tables of contents, the Info
3588 formatting commands ignore the contents commands. But the contents are
3589 included in plain text output (generated by @code{makeinfo
3590 --no-headers}), unless @code{makeinfo} is writing its output to standard
3591 output.
3592
3593 When @code{makeinfo} writes a short table of contents while producing
3594 HTML output, the links in the short table of contents point to
3595 corresponding entries in the full table of contents rather than the text
3596 of the document. The links in the full table of contents point to the
3597 main text of the document.
3598
3599 In the past, the contents commands were sometimes placed at the end of
3600 the file, after any indices and just before the @code{@@bye}, but we
3601 no longer recommend this.
3602
3603 @findex setcontentsaftertitlepage
3604 @findex setshortcontentsaftertitlepage
3605 @cindex Contents, after title page
3606 @cindex Table of contents, after title page
3607 However, since many existing Texinfo documents still do have the
3608 @code{@@contents} at the end of the manual, if you are a user printing
3609 a manual, you may wish to force the contents to be printed after the
3610 title page. You can do this by specifying
3611 @code{@@setcontentsaftertitlepage} and/or
3612 @code{@@setshortcontentsaftertitlepage}. The first prints only the
3613 main contents after the @code{@@end titlepage}; the second prints both
3614 the short contents and the main contents. In either case, any
3615 subsequent @code{@@contents} or @code{@@shortcontents} is ignored
3616 (unless, erroneously, no @code{@@end titlepage} is ever encountered).
3617
3618 You need to include the @code{@@set@dots{}contentsaftertitlepage}
3619 commands early in the document (just after @code{@@setfilename}, for
3620 example). We recommend using @command{texi2dvi} (@pxref{Format with
3621 texi2dvi}) to specify this without altering the source file at all. For
3622 example:
3623 @example
3624 texi2dvi --texinfo=@@setcontentsaftertitlepage foo.texi
3625 @end example
3626
3627
3628 @node The Top Node
3629 @section The `Top' Node and Master Menu
3630 @cindex Top node
3631 @cindex Node, `Top'
3632
3633 The `Top' node is the node in which a reader enters an Info manual.
3634 As such, it should begin with a brief description of the manual
3635 (including the version number), and end with a master menu for the
3636 whole manual. Of course you should include any other general
3637 information you feel a reader would find helpful.
3638
3639 @findex top
3640 It is conventional and desirable to write an @code{@@top} sectioning
3641 command line containing the title of the document immediately after
3642 the @code{@@node Top} line (@pxref{makeinfo top command, , The
3643 @code{@@top} Sectioning Command}).
3644
3645 The contents of the `Top' node should appear only in the online output;
3646 none of it should appear in printed output, so enclose it between
3647 @code{@@ifnottex} and @code{@@end ifnottex} commands. (@TeX{} does not
3648 print either an @code{@@node} line or a menu; they appear only in Info;
3649 strictly speaking, you are not required to enclose these parts between
3650 @code{@@ifnottex} and @code{@@end ifnottex}, but it is simplest to do
3651 so. @xref{Conditionals, , Conditionally Visible Text}.)
3652
3653 @menu
3654 * Top Node Example::
3655 * Master Menu Parts::
3656 @end menu
3657
3658
3659 @node Top Node Example
3660 @subsection Top Node Example
3661
3662 @cindex Top node example
3663
3664 Here is an example of a Top node.
3665
3666 @example
3667 @group
3668 @@ifnottex
3669 @@node Top
3670 @@top Sample Title
3671
3672 @@insertcopying
3673 @@end ifnottex
3674 @end group
3675
3676 Additional general information.
3677
3678 @group
3679 @@menu
3680 * First Chapter::
3681 * Second Chapter::
3682 @dots{}
3683 * Index::
3684 @end group
3685 @@end menu
3686 @end example
3687
3688
3689 @node Master Menu Parts
3690 @subsection Parts of a Master Menu
3691 @cindex Master menu
3692 @cindex Menu, master
3693 @cindex Parts of a master menu
3694
3695 A @dfn{master menu} is a detailed main menu listing all the nodes in a
3696 file.
3697
3698 A master menu is enclosed in @code{@@menu} and @code{@@end menu}
3699 commands and does not appear in the printed document.
3700
3701 Generally, a master menu is divided into parts.
3702
3703 @itemize @bullet
3704 @item
3705 The first part contains the major nodes in the Texinfo file: the nodes
3706 for the chapters, chapter-like sections, and the appendices.
3707
3708 @item
3709 The second part contains nodes for the indices.
3710
3711 @item
3712 @findex detailmenu
3713 @cindex Detailed menu
3714 The third and subsequent parts contain a listing of the other, lower
3715 level nodes, often ordered by chapter. This way, rather than go
3716 through an intermediary menu, an inquirer can go directly to a
3717 particular node when searching for specific information. These menu
3718 items are not required; add them if you think they are a
3719 convenience. If you do use them, put @code{@@detailmenu} before the
3720 first one, and @code{@@end detailmenu} after the last; otherwise,
3721 @code{makeinfo} will get confused.
3722 @end itemize
3723
3724 Each section in the menu can be introduced by a descriptive line. So
3725 long as the line does not begin with an asterisk, it will not be
3726 treated as a menu entry. (@xref{Writing a Menu}, for more
3727 information.)
3728
3729 For example, the master menu for this manual looks like the following
3730 (but has many more entries):
3731
3732 @example
3733 @group
3734 @@menu
3735 * Copying Conditions:: Your rights.
3736 * Overview:: Texinfo in brief.
3737 @dots{}
3738 @end group
3739 @group
3740 * Command and Variable Index::
3741 * General Index::
3742 @end group
3743
3744 @group
3745 @@detailmenu
3746 --- The Detailed Node Listing ---
3747
3748 Overview of Texinfo
3749
3750 * Reporting Bugs:: @dots{}
3751 @dots{}
3752 @end group
3753
3754 @group
3755 Beginning a Texinfo File
3756
3757 * Sample Beginning:: @dots{}
3758 @dots{}
3759 @@end detailmenu
3760 @@end menu
3761 @end group
3762 @end example
3763
3764
3765 @node Global Document Commands
3766 @section Global Document Commands
3767 @cindex Global Document Commands
3768
3769 Besides the basic commands mentioned in the previous sections, here are
3770 additional commands which affect the document as a whole. They are
3771 generally all given before the Top node, if they are given at all.
3772
3773 @menu
3774 * documentdescription:: Document summary for the HTML output.
3775 * setchapternewpage:: Start chapters on right-hand pages.
3776 * paragraphindent:: Specify paragraph indentation.
3777 * firstparagraphindent:: Suppress indentation of the first paragraph.
3778 * exampleindent:: Specify environment indentation.
3779 @end menu
3780
3781
3782 @node documentdescription
3783 @subsection @code{@@documentdescription}: Summary Text
3784 @cindex Document description
3785 @cindex Description of document
3786 @cindex Summary of document
3787 @cindex Abstract of document
3788 @cindex <meta> HTML tag, and document description
3789 @findex documentdescription
3790
3791 When producing HTML output for a document, @command{makeinfo} writes a
3792 @samp{<meta>} element in the @samp{<head>} to give some idea of the
3793 content of the document. By default, this @dfn{description} is the title
3794 of the document, taken from the @code{@@settitle} command
3795 (@pxref{settitle}). To change this, use the @code{@@documentdescription}
3796 environment, as in:
3797
3798 @example
3799 @@documentdescription
3800 descriptive text.
3801 @@end documentdescription
3802 @end example
3803
3804 @noindent
3805 This will produce the following output in the @samp{<head>} of the HTML:
3806
3807 @example
3808 <meta name=description content="descriptive text.">
3809 @end example
3810
3811 @code{@@documentdescription} must be specified before the first node of
3812 the document.
3813
3814
3815 @node setchapternewpage
3816 @subsection @code{@@setchapternewpage}:
3817 @cindex Starting chapters
3818 @cindex Pages, starting odd
3819 @findex setchapternewpage
3820
3821 In an officially bound book, text is usually printed on both sides of
3822 the paper, chapters start on right-hand pages, and right-hand pages have
3823 odd numbers. But in short reports, text often is printed only on one
3824 side of the paper. Also in short reports, chapters sometimes do not
3825 start on new pages, but are printed on the same page as the end of the
3826 preceding chapter, after a small amount of vertical whitespace.
3827
3828 You can use the @code{@@setchapternewpage} command with various
3829 arguments to specify how @TeX{} should start chapters and whether it
3830 should format headers for printing on one or both sides of the paper
3831 (single-sided or double-sided printing).
3832
3833 Write the @code{@@setchapternewpage} command at the beginning of a
3834 line followed by its argument.
3835
3836 For example, you would write the following to cause each chapter to
3837 start on a fresh odd-numbered page:
3838
3839 @example
3840 @@setchapternewpage odd
3841 @end example
3842
3843 You can specify one of three alternatives with the
3844 @code{@@setchapternewpage} command:
3845
3846 @table @asis
3847
3848 @item @code{@@setchapternewpage off}
3849 Cause @TeX{} to typeset a new chapter on the same page as the last
3850 chapter, after skipping some vertical whitespace. Also, cause @TeX{} to
3851 format page headers for single-sided printing.
3852
3853 @item @code{@@setchapternewpage on}
3854 Cause @TeX{} to start new chapters on new pages and to format page
3855 headers for single-sided printing. This is the form most often used for
3856 short reports or personal printing. This is the default.
3857
3858 @item @code{@@setchapternewpage odd}
3859 Cause @TeX{} to start new chapters on new, odd-numbered pages
3860 (right-handed pages) and to typeset for double-sided printing. This is
3861 the form most often used for books and manuals.
3862 @end table
3863
3864 Texinfo does not have an @code{@@setchapternewpage even} command,
3865 because there is no printing tradition of starting chapters or books on
3866 an even-numbered page.
3867
3868 If you don't like the default headers that @code{@@setchapternewpage}
3869 sets, you can explicit control them with the @code{@@headings} command.
3870 @xref{headings on off, , The @code{@@headings} Command}.
3871
3872 At the beginning of a manual or book, pages are not numbered---for
3873 example, the title and copyright pages of a book are not numbered. By
3874 convention, table of contents and frontmatter pages are numbered with
3875 roman numerals and not in sequence with the rest of the document.
3876
3877 Since an Info file does not have pages, the @code{@@setchapternewpage}
3878 command has no effect on it.
3879
3880 We recommend not including any @code{@@setchapternewpage} command in
3881 your manual sources at all, since the desired output is not intrinsic to
3882 the document. For a particular hard copy run, if you don't want the
3883 default option (no blank pages, same headers on all pages) use the
3884 @option{--texinfo} option to @command{texi2dvi} to specify the output
3885 you want.
3886
3887
3888 @node paragraphindent
3889 @subsection @code{@@paragraphindent}: Paragraph Indenting
3890 @cindex Indenting paragraphs, control of
3891 @cindex Paragraph indentation control
3892 @findex paragraphindent
3893
3894 The Texinfo processors may insert whitespace at the beginning of the
3895 first line of each paragraph, thereby indenting that paragraph. You can
3896 use the @code{@@paragraphindent} command to specify this indentation.
3897 Write an @code{@@paragraphindent} command at the beginning of a line
3898 followed by either @samp{asis} or a number:
3899
3900 @example
3901 @@paragraphindent @var{indent}
3902 @end example
3903
3904 The indentation is according to the value of @var{indent}:
3905
3906 @table @asis
3907 @item @code{asis}
3908 Do not change the existing indentation (not implemented in @TeX{}).
3909
3910 @item @code{none}
3911 @itemx 0
3912 Omit all indentation.
3913
3914 @item @var{n}
3915 Indent by @var{n} space characters in Info output, by @var{n} ems in
3916 @TeX{}.
3917
3918 @end table
3919
3920 The default value of @var{indent} is 3. @code{@@paragraphindent} is
3921 ignored for HTML output.
3922
3923 It is best to write the @code{@@paragraphindent} command before the
3924 end-of-header line at the beginning of a Texinfo file, so the region
3925 formatting commands indent paragraphs as specified. @xref{Start of
3926 Header}.
3927
3928 A peculiarity of the @code{texinfo-format-buffer} and
3929 @code{texinfo-format-region} commands is that they do not indent (nor
3930 fill) paragraphs that contain @code{@@w} or @code{@@*} commands.
3931
3932
3933 @node firstparagraphindent
3934 @subsection @code{@@firstparagraphindent}: Indenting After Headings
3935 @cindex First paragraph, suppressing indentation of
3936 @cindex Suppressing first paragraph indentation
3937 @cindex Preventing first paragraph indentation
3938 @cindex Indenting, suppressing of first paragraph
3939 @cindex Headings, indentation after
3940 @findex firstparagraphindent
3941
3942 As you can see in the present manual, the first paragraph in any
3943 section is not indented by default. Typographically, indentation is a
3944 paragraph separator, which means that it is unnecessary when a new
3945 section begins. This indentation is controlled with the
3946 @code{@@firstparagraphindent} command:
3947
3948 @example
3949 @@firstparagraphindent @var{word}
3950 @end example
3951
3952 The first paragraph after a heading is indented according to the value
3953 of @var{word}:
3954
3955 @table @asis
3956 @item @code{none}
3957 Prevents the first paragraph from being indented (default).
3958 This option is ignored by @command{makeinfo} if
3959 @code{@@paragraphindent asis} is in effect.
3960
3961 @item @code{insert}
3962 Include normal paragraph indentation. This respects the paragraph
3963 indentation set by a @code{@@paragraphindent} command
3964 (@pxref{paragraphindent}).
3965 @end table
3966
3967 For HTML and XML output, the @code{@@firstparagraphindent} setting is
3968 ignored.
3969
3970 It is best to write the @code{@@paragraphindent} command before the
3971 end-of-header line at the beginning of a Texinfo file, so the region
3972 formatting commands indent paragraphs as specified. @xref{Start of
3973 Header}.
3974
3975
3976 @node exampleindent
3977 @subsection @code{@@exampleindent}: Environment Indenting
3978 @cindex Indenting environments
3979 @cindex Environment indentation
3980 @cindex Example indentation
3981 @findex exampleindent
3982
3983 The Texinfo processors indent each line of @code{@@example} and similar
3984 environments. You can use the @code{@@exampleindent} command to specify
3985 this indentation. Write an @code{@@exampleindent} command at the
3986 beginning of a line followed by either @samp{asis} or a number:
3987
3988 @example
3989 @@exampleindent @var{indent}
3990 @end example
3991
3992 @code{@@exampleindent} is ignored for HTML output. Otherwise, the
3993 indentation is according to the value of @var{indent}:
3994
3995 @table @asis
3996 @item @code{asis}
3997 Do not change the existing indentation (not implemented in @TeX{}).
3998
3999 @item 0
4000 Omit all indentation.
4001
4002 @item @var{n}
4003 Indent environments by @var{n} space characters in Info output, by
4004 @var{n} ems in @TeX{}.
4005
4006 @end table
4007
4008 The default value of @var{indent} is 5 spaces in Info, and 0.4@dmn{in}
4009 in @TeX{}, which is somewhat less. (The reduction is to help @TeX{}
4010 fit more characters onto physical lines.)
4011
4012 It is best to write the @code{@@exampleindent} command before the
4013 end-of-header line at the beginning of a Texinfo file, so the region
4014 formatting commands indent paragraphs as specified. @xref{Start of
4015 Header}.
4016
4017
4018 @node Software Copying Permissions
4019 @section Software Copying Permissions
4020 @cindex Software copying permissions
4021 @cindex Copying software
4022 @cindex Distribution
4023 @cindex License agreement
4024
4025 If the Texinfo file has a section containing the ``General Public
4026 License'' and the distribution information and a warranty disclaimer for
4027 the software that is documented, we recommend placing this right after
4028 the `Top' node. The General Public License is very important to Project
4029 GNU software. It ensures that you and others will continue to have a
4030 right to use and share the software.
4031
4032 The copying and distribution information and the disclaimer are followed
4033 by an introduction or else by the first chapter of the manual.
4034
4035 @cindex Introduction, as part of file
4036 Although an introduction is not a required part of a Texinfo file, it
4037 is very helpful. Ideally, it should state clearly and concisely what
4038 the file is about and who would be interested in reading it. In
4039 general, an introduction would follow the licensing and distribution
4040 information, although sometimes people put it earlier in the document.
4041
4042
4043 @node Ending a File
4044 @chapter Ending a Texinfo File
4045 @cindex Ending a Texinfo file
4046 @cindex Texinfo file ending
4047 @cindex File ending
4048 @findex bye
4049
4050 The end of a Texinfo file should include commands to create indices,
4051 and the @code{@@bye} command to mark the last line to be processed.
4052
4053 For example:
4054
4055 @example
4056 @@node Index
4057 @@unnumbered Index
4058
4059 @@printindex cp
4060
4061 @@bye
4062 @end example
4063
4064 @menu
4065 * Printing Indices & Menus:: How to print an index in hardcopy and
4066 generate index menus in Info.
4067 * File End:: How to mark the end of a file.
4068 @end menu
4069
4070
4071 @node Printing Indices & Menus
4072 @section Printing Indices and Menus
4073 @cindex Printing an index
4074 @cindex Indices, printing and menus
4075 @cindex Generating menus with indices
4076 @cindex Menus generated with indices
4077
4078 To print an index means to include it as part of a manual or Info file.
4079 This does not happen automatically just because you use @code{@@cindex}
4080 or other index-entry generating commands in the Texinfo file; those just
4081 cause the raw data for the index to be accumulated. To generate an
4082 index, you must include the @code{@@printindex} command at the place in
4083 the document where you want the index to appear. Also, as part of the
4084 process of creating a printed manual, you must run a program called
4085 @code{texindex} (@pxref{Hardcopy}) to sort the raw data to produce a
4086 sorted index file. The sorted index file is what is actually used to
4087 print the index.
4088
4089 Texinfo offers six separate types of predefined index, which suffice
4090 in most cases. @xref{Indices}, for information on this, as well
4091 defining your own new indices, combining indices, and, most
4092 importantly advice on writing the actual index entries. This section
4093 focuses on printing indices, which is done with the
4094 @code{@@printindex} command.
4095
4096 @findex printindex
4097 @code{@@printindex} takes one argument, a two-letter index
4098 abbreviation. It reads the corresponding sorted index file (for
4099 printed output), and formats it appropriately into an index.
4100
4101 The @code{@@printindex} command does not generate a chapter heading
4102 for the index, since different manuals have different needs.
4103 Consequently, you should precede the @code{@@printindex} command with
4104 a suitable section or chapter command (usually @code{@@appendix} or
4105 @code{@@unnumbered}) to supply the chapter heading and put the index
4106 into the table of contents. Precede the chapter heading with an
4107 @code{@@node} line as usual.
4108
4109 For example:
4110
4111 @smallexample
4112 @group
4113 @@node Variable Index
4114 @@unnumbered Variable Index
4115
4116 @@printindex vr
4117 @end group
4118
4119 @group
4120 @@node Concept Index
4121 @@unnumbered Concept Index
4122
4123 @@printindex cp
4124 @end group
4125 @end smallexample
4126
4127 If you have more than one index, we recommend placing the concept index last.
4128
4129 @itemize
4130 @item
4131 In printed output, @code{@@printindex} produces a traditional
4132 two-column index, with dot leaders between the index terms and page
4133 numbers.
4134
4135 @item
4136 In Info output, @code{@@printindex} produces a special menu containing
4137 the line number of the entry, relative to the start of the node. Info
4138 readers can use this to go to the exact line of an entry, not just the
4139 containing node. (Older Info readers will just go to the node.)
4140 Here's an example:
4141
4142 @smallexample
4143 * First index entry: Top. (line 7)
4144 @end smallexample
4145
4146 @noindent The actual number of spaces is variable, to right-justify
4147 the line number; it's been reduced here to make the line fit in the
4148 printed manual.
4149
4150 @item
4151 In plain text output, @code{@@printindex} produces the same menu, but
4152 the line numbers are relative to the start of the file, since that's
4153 more convenient for that format.
4154
4155 @item
4156 In HTML and Docbook output, @code{@@printindex} produces links
4157 to the index entries.
4158
4159 @item
4160 In XML output, it simply records the index to be printed.
4161 @end itemize
4162
4163 It's not possible to generate an index when writing to standard
4164 output; @command{makeinfo} generates a warning in this case.
4165
4166
4167 @node File End
4168 @section @code{@@bye} File Ending
4169 @findex bye
4170
4171 An @code{@@bye} command terminates Texinfo processing. None of the
4172 formatters read anything following @code{@@bye}. The @code{@@bye}
4173 command should be on a line by itself.
4174
4175 If you wish, you may follow the @code{@@bye} line with notes. These
4176 notes will not be formatted and will not appear in either Info or a
4177 printed manual; it is as if text after @code{@@bye} were within
4178 @code{@@ignore} @dots{} @code{@@end ignore}. Also, you may follow the
4179 @code{@@bye} line with a local variables list for XEmacs.
4180 @xref{Compile-Command, , Using Local Variables and the Compile Command},
4181 for more information.
4182
4183
4184 @node Structuring
4185 @chapter Chapter Structuring
4186 @cindex Chapter structuring
4187 @cindex Structuring of chapters
4188
4189 The @dfn{chapter structuring} commands divide a document into a hierarchy of
4190 chapters, sections, subsections, and subsubsections. These commands
4191 generate large headings; they also provide information for the table
4192 of contents of a printed manual (@pxref{Contents, , Generating a Table
4193 of Contents}).@refill
4194
4195 The chapter structuring commands do not create an Info node structure,
4196 so normally you should put an @code{@@node} command immediately before
4197 each chapter structuring command (@pxref{Nodes}). The only time you
4198 are likely to use the chapter structuring commands without using the
4199 node structuring commands is if you are writing a document that
4200 contains no cross references and will never be transformed into Info
4201 format.@refill
4202
4203 It is unlikely that you will ever write a Texinfo file that is
4204 intended only as an Info file and not as a printable document. If you
4205 do, you might still use chapter structuring commands to create a
4206 heading at the top of each node---but you don't need to.@refill
4207
4208 @menu
4209 * Tree Structuring:: A manual is like an upside down tree @dots{}
4210 * Structuring Command Types:: How to divide a manual into parts.
4211 * makeinfo top:: The @code{@@top} command, part of the `Top' node.
4212 * chapter::
4213 * unnumbered & appendix::
4214 * majorheading & chapheading::
4215 * section::
4216 * unnumberedsec appendixsec heading::
4217 * subsection::
4218 * unnumberedsubsec appendixsubsec subheading::
4219 * subsubsection:: Commands for the lowest level sections.
4220 * Raise/lower sections:: How to change commands' hierarchical level.
4221 @end menu
4222
4223
4224 @node Tree Structuring
4225 @section Tree Structure of Sections
4226 @cindex Tree structuring
4227
4228 A Texinfo file is usually structured like a book with chapters,
4229 sections, subsections, and the like. This structure can be visualized
4230 as a tree (or rather as an upside-down tree) with the root at the top
4231 and the levels corresponding to chapters, sections, subsection, and
4232 subsubsections.@refill
4233
4234 Here is a diagram that shows a Texinfo file with three chapters,
4235 each of which has two sections.@refill
4236
4237 @example
4238 @group
4239 Top
4240 |
4241 -------------------------------------
4242 | | |
4243 Chapter 1 Chapter 2 Chapter 3
4244 | | |
4245 -------- -------- --------
4246 | | | | | |
4247 Section Section Section Section Section Section
4248 1.1 1.2 2.1 2.2 3.1 3.2
4249
4250 @end group
4251 @end example
4252
4253 In a Texinfo file that has this structure, the beginning of Chapter 2
4254 looks like this:@refill
4255
4256 @example
4257 @group
4258 @@node Chapter 2, Chapter 3, Chapter 1, top
4259 @@chapter Chapter 2
4260 @end group
4261 @end example
4262
4263 The chapter structuring commands are described in the sections that
4264 follow; the @code{@@node} and @code{@@menu} commands are described in
4265 following chapters. (@xref{Nodes}, and see @ref{Menus}.)@refill
4266
4267
4268 @node Structuring Command Types
4269 @section Structuring Command Types
4270
4271 The chapter structuring commands fall into four groups or series, each
4272 of which contains structuring commands corresponding to the
4273 hierarchical levels of chapters, sections, subsections, and
4274 subsubsections.@refill
4275
4276 The four groups are the @code{@@chapter} series, the
4277 @code{@@unnumbered} series, the @code{@@appendix} series, and the
4278 @code{@@heading} series.@refill
4279
4280 Each command produces titles that have a different appearance on the
4281 printed page or Info file; only some of the commands produce
4282 titles that are listed in the table of contents of a printed book or
4283 manual.@refill
4284
4285 @itemize @bullet
4286 @item
4287 The @code{@@chapter} and @code{@@appendix} series of commands produce
4288 numbered or lettered entries both in the body of a printed work and in
4289 its table of contents.@refill
4290
4291 @item
4292 The @code{@@unnumbered} series of commands produce unnumbered entries
4293 both in the body of a printed work and in its table of contents. The
4294 @code{@@top} command, which has a special use, is a member of this
4295 series (@pxref{makeinfo top, , @code{@@top}}). An @code{@@unnumbered}
4296 section should be associated with a node and be a normal part of the
4297 document structure.
4298
4299 @item
4300 The @code{@@heading} series of commands produce simple unnumbered
4301 headings that do not appear in a table of contents, are not associated
4302 with nodes, and cannot be cross-referenced. The heading commands
4303 never start a new page.
4304
4305 @item
4306 The @code{@@majorheading} command is similar to @code{@@chapheading},
4307 except that it generates a larger vertical whitespace before the
4308 heading.
4309
4310 @item
4311 When an @code{@@setchapternewpage} command says to do so, the
4312 @code{@@chapter}, @code{@@unnumbered}, and @code{@@appendix} commands
4313 start new pages in the printed manual; the @code{@@heading} commands
4314 do not.@refill
4315 @end itemize
4316
4317 Here are the four groups of chapter structuring commands:
4318
4319 @tex
4320 {\globaldefs = 1 \smallfonts}
4321 @end tex
4322
4323 @multitable @columnfractions .19 .30 .29 .22
4324 @item @tab @tab @tab No new page
4325 @item @i{Numbered} @tab @i{Unnumbered} @tab @i{Lettered/numbered} @tab @i{Unnumbered}
4326 @item In contents @tab In contents @tab In contents @tab Not in contents
4327 @item @tab @code{@@top} @tab @tab @code{@@majorheading}
4328 @item @code{@@chapter} @tab @code{@@unnumbered} @tab @code{@@appendix} @tab @code{@@chapheading}
4329 @item @code{@@section} @tab @code{@@unnumberedsec} @tab @code{@@appendixsec} @tab @code{@@heading}
4330 @item @code{@@subsection} @tab @code{@@unnumberedsubsec} @tab @code{@@appendixsubsec} @tab @code{@@subheading}
4331 @item @code{@@subsubsection} @tab @code{@@unnumberedsubsubsec} @tab @code{@@appendixsubsubsec} @tab @code{@@subsubheading}
4332 @end multitable
4333 @tex
4334 {\globaldefs = 1 \textfonts}
4335 @end tex
4336
4337
4338 @node makeinfo top
4339 @section @code{@@top}
4340
4341 The @code{@@top} command is a special sectioning command that you use
4342 only after an @samp{@@node Top} line at the beginning of a Texinfo file.
4343 The @code{@@top} command tells the @code{makeinfo} formatter which node
4344 is the `Top' node, so it can use it as the root of the node tree if your
4345 manual uses implicit node pointers. It has the same typesetting effect as
4346 @code{@@unnumbered} (@pxref{unnumbered & appendix, , @code{@@unnumbered}
4347 and @code{@@appendix}}). For detailed information, see @ref{makeinfo
4348 top command, , The @code{@@top} Command}.
4349
4350 The @code{@@top} node and its menu (if any) is conventionally wrapped in
4351 an @code{@@ifnottex} conditional so that it will appear only in Info and
4352 HTML output, not @TeX{}.
4353
4354
4355 @node chapter
4356 @comment node-name, next, previous, up
4357 @section @code{@@chapter}
4358 @findex chapter
4359
4360 @code{@@chapter} identifies a chapter in the document. Write the
4361 command at the beginning of a line and follow it on the same line by
4362 the title of the chapter.@refill
4363
4364 For example, this chapter in this manual is entitled ``Chapter
4365 Structuring''; the @code{@@chapter} line looks like this:@refill
4366
4367 @example
4368 @@chapter Chapter Structuring
4369 @end example
4370
4371 In @TeX{}, the @code{@@chapter} command creates a chapter in the
4372 document, specifying the chapter title. The chapter is numbered
4373 automatically.@refill
4374
4375 In Info, the @code{@@chapter} command causes the title to appear on a
4376 line by itself, with a line of asterisks inserted underneath. Thus,
4377 in Info, the above example produces the following output:@refill
4378
4379 @example
4380 Chapter Structuring
4381 *******************
4382 @end example
4383
4384 @findex centerchap
4385 Texinfo also provides a command @code{@@centerchap}, which is analogous
4386 to @code{@@unnumbered}, but centers its argument in the printed output.
4387 This kind of stylistic choice is not usually offered by Texinfo.
4388 @c but the Hacker's Dictionary wanted it ...
4389
4390
4391 @node unnumbered & appendix
4392 @section @code{@@unnumbered} and @code{@@appendix}
4393 @findex unnumbered
4394 @findex appendix
4395
4396 Use the @code{@@unnumbered} command to create a chapter that appears
4397 in a printed manual without chapter numbers of any kind. Use the
4398 @code{@@appendix} command to create an appendix in a printed manual
4399 that is labelled by letter (`A', `B', @dots{}) instead of by number.
4400
4401 Write an @code{@@appendix} or @code{@@unnumbered} command at the
4402 beginning of a line and follow it on the same line by the title, as
4403 you would if you were creating a chapter.
4404
4405
4406 @node majorheading & chapheading
4407 @section @code{@@majorheading}, @code{@@chapheading}
4408 @findex majorheading
4409 @findex chapheading
4410
4411 The @code{@@majorheading} and @code{@@chapheading} commands put
4412 chapter-like headings in the body of a document.@refill
4413
4414 However, neither command causes @TeX{} to produce a numbered heading
4415 or an entry in the table of contents; and neither command causes
4416 @TeX{} to start a new page in a printed manual.@refill
4417
4418 In @TeX{}, an @code{@@majorheading} command generates a larger vertical
4419 whitespace before the heading than an @code{@@chapheading} command but
4420 is otherwise the same.
4421
4422 In Info,
4423 the @code{@@majorheading} and
4424 @code{@@chapheading} commands are equivalent to
4425 @code{@@chapter}: the title is printed on a line by itself with a line
4426 of asterisks underneath. (@xref{chapter, , @code{@@chapter}}.)@refill
4427
4428
4429 @node section
4430 @section @code{@@section}
4431 @findex section
4432
4433 A @code{@@section} command identifies a section within a chapter unit,
4434 whether created with @code{@@chapter}, @code{@@unnumbered}, or
4435 @code{@@appendix}, following the numbering scheme of the chapter-level
4436 command. Thus, within a @code{@@chapter} chapter numbered `1', the
4437 section is numbered like `1.2'; within an @code{@@appendix}
4438 ``chapter'' labeled `A', the section is numbered like `A.2'; within an
4439 @code{@@unnumbered} chapter, the section gets no number.
4440
4441 For example, this section is headed with an @code{@@section} command
4442 and looks like this in the Texinfo file:
4443
4444 @example
4445 @@section @@code@{@@@@section@}
4446 @end example
4447
4448 To create a section, write the @code{@@section} command at the
4449 beginning of a line and follow it on the same line by the section
4450 title. The output is underlined with @samp{=} in Info.
4451
4452 Thus,
4453
4454 @example
4455 @@section This is a section
4456 @end example
4457
4458 @noindent
4459 might produce the following in Info:
4460
4461 @example
4462 @group
4463 5.7 This is a section
4464 =====================
4465 @end group
4466 @end example
4467
4468
4469 @node unnumberedsec appendixsec heading
4470 @section @code{@@unnumberedsec}, @code{@@appendixsec}, @code{@@heading}
4471 @findex unnumberedsec
4472 @findex appendixsec
4473 @findex heading
4474
4475 The @code{@@unnumberedsec}, @code{@@appendixsec}, and @code{@@heading}
4476 commands are, respectively, the unnumbered, appendix-like, and
4477 heading-like equivalents of the @code{@@section} command, as described
4478 in the previous section.
4479
4480 @table @code
4481 @item @@unnumberedsec
4482 The @code{@@unnumberedsec} command may be used within an
4483 unnumbered chapter or within a regular chapter or appendix to
4484 provide an unnumbered section.@refill
4485
4486 @item @@appendixsec
4487 @itemx @@appendixsection
4488 @code{@@appendixsection} is a longer spelling of the
4489 @code{@@appendixsec} command; the two are synonymous.@refill
4490 @findex appendixsection
4491
4492 Conventionally, the @code{@@appendixsec} or @code{@@appendixsection}
4493 command is used only within appendices.@refill
4494
4495 @item @@heading
4496 You may use the @code{@@heading} command anywhere you wish for a
4497 section-style heading that will not appear in the table of contents.@refill
4498 @end table
4499
4500 @code{@@unnumberedsec} and @code{@@appendixsec} do not need to be used
4501 in ordinary circumstances, because @code{@@section} may also be used
4502 within @code{@@unnumbered} and @code{@@appendix} chapters; again, see
4503 the previous section.
4504
4505
4506 @node subsection
4507 @section The @code{@@subsection} Command
4508 @findex subsection
4509
4510 Subsections are to sections as sections are to chapters.
4511 (@xref{section, , @code{@@section}}.) In Info, subsection titles are
4512 underlined with @samp{-}. For example,
4513
4514 @example
4515 @@subsection This is a subsection
4516 @end example
4517
4518 @noindent
4519 produces
4520
4521 @example
4522 @group
4523 1.2.3 This is a subsection
4524 --------------------------
4525 @end group
4526 @end example
4527
4528 In a printed manual, subsections are listed in the table of contents
4529 and are numbered three levels deep.@refill
4530
4531
4532 @node unnumberedsubsec appendixsubsec subheading
4533 @section The @code{@@subsection}-like Commands
4534 @cindex Subsection-like commands
4535 @findex unnumberedsubsec
4536 @findex appendixsubsec
4537 @findex subheading
4538
4539 The @code{@@unnumberedsubsec}, @code{@@appendixsubsec}, and
4540 @code{@@subheading} commands are, respectively, the unnumbered,
4541 appendix-like, and heading-like equivalents of the @code{@@subsection}
4542 command. (@xref{subsection, , @code{@@subsection}}.)
4543
4544 In Info, the @code{@@subsection}-like commands generate a title
4545 underlined with hyphens. In a printed manual, an @code{@@subheading}
4546 command produces a heading like that of a subsection except that it is
4547 not numbered and does not appear in the table of contents. Similarly,
4548 an @code{@@unnumberedsubsec} command produces an unnumbered heading like
4549 that of a subsection and an @code{@@appendixsubsec} command produces a
4550 subsection-like heading labelled with a letter and numbers; both of
4551 these commands produce headings that appear in the table of
4552 contents.
4553
4554 @code{@@unnumberedsubsec} and @code{@@appendixsubsec} do not need to
4555 be used in ordinary circumstances, because @code{@@subsection} may
4556 also be used within sections of @code{@@unnumbered} and
4557 @code{@@appendix} chapters (@pxref{section,,@code{section}}).
4558
4559
4560 @node subsubsection
4561 @section The `subsub' Commands
4562 @cindex Subsub commands
4563 @findex subsubsection
4564 @findex unnumberedsubsubsec
4565 @findex appendixsubsubsec
4566 @findex subsubheading
4567
4568 The fourth and lowest level sectioning commands in Texinfo are the
4569 `subsub' commands. They are:@refill
4570
4571 @table @code
4572 @item @@subsubsection
4573 Subsubsections are to subsections as subsections are to sections.
4574 (@xref{subsection, , @code{@@subsection}}.) In a printed manual,
4575 subsubsection titles appear in the table of contents and are numbered
4576 four levels deep.@refill
4577
4578 @item @@unnumberedsubsubsec
4579 Unnumbered subsubsection titles appear in the table of contents of a
4580 printed manual, but lack numbers. Otherwise, unnumbered
4581 subsubsections are the same as subsubsections. In Info, unnumbered
4582 subsubsections look exactly like ordinary subsubsections.@refill
4583
4584 @item @@appendixsubsubsec
4585 Conventionally, appendix commands are used only for appendices and are
4586 lettered and numbered appropriately in a printed manual. They also
4587 appear in the table of contents. In Info, appendix subsubsections look
4588 exactly like ordinary subsubsections.@refill
4589
4590 @item @@subsubheading
4591 The @code{@@subsubheading} command may be used anywhere that you need
4592 a small heading that will not appear in the table of contents. In
4593 Info, subsubheadings look exactly like ordinary subsubsection
4594 headings.@refill
4595 @end table
4596
4597 @code{@@unnumberedsubsubsec} and @code{@@appendixsubsubsec} do not
4598 need to be used in ordinary circumstances, because
4599 @code{@@subsubsection} may also be used within subsections of
4600 @code{@@unnumbered} and @code{@@appendix} chapters
4601 (@pxref{section,,@code{section}}).
4602
4603
4604 In Info, `subsub' titles are underlined with periods.
4605 For example,@refill
4606
4607 @example
4608 @@subsubsection This is a subsubsection
4609 @end example
4610
4611 @noindent
4612 produces
4613
4614 @example
4615 @group
4616 1.2.3.4 This is a subsubsection
4617 ...............................
4618 @end group
4619 @end example
4620
4621
4622 @node Raise/lower sections
4623 @section @code{@@raisesections} and @code{@@lowersections}
4624 @findex raisesections
4625 @findex lowersections
4626 @cindex Raising and lowering sections
4627 @cindex Lowering and raising sections
4628 @cindex Sections, raising and lowering
4629
4630 The @code{@@raisesections} and @code{@@lowersections} commands
4631 implicitly raise and lower the hierarchical level of following
4632 chapters, sections and the other sectioning commands.
4633
4634 That is, the @code{@@raisesections} command changes sections to
4635 chapters, subsections to sections, and so on. Conversely, the
4636 @code{@@lowersections} command changes chapters to sections, sections
4637 to subsections, and so on. Thus, an @code{@@lowersections} command
4638 cancels an @code{@@raisesections} command, and vice versa.
4639
4640 @cindex Include files, and section levels
4641 You can use @code{@@lowersections} to include text written as an outer
4642 or standalone Texinfo file in another Texinfo file as an inner,
4643 included file. Typical usage looks like this:
4644
4645 @example
4646 @@lowersections
4647 @@include somefile.texi
4648 @@raisesections
4649 @end example
4650
4651 @noindent (Without the @code{@@raisesections}, all the subsequent
4652 sections in the document would be lowered.)
4653
4654 If the included file being lowered has a @code{@@top} node, you'll
4655 need to conditionalize its inclusion with a flag (@pxref{set value}).
4656
4657 Another difficulty can arise with documents that use the (recommended)
4658 feature of @command{makeinfo} for implicitly determining node
4659 pointers. Since @command{makeinfo} must assume a hierarchically
4660 organized document to determine the pointers, you cannot just
4661 arbitrarily sprinkle @code{@@raisesections} and @code{@@lowersections}
4662 commands in the document. The final result has to have menus that
4663 take the raising and lowering into account. Therefore, as a practical
4664 matter, you generally only want to raise or lower large chunks,
4665 usually in external files as shown above.
4666
4667 Repeated use of the commands continue to raise or lower the
4668 hierarchical level a step at a time. An attempt to raise above
4669 `chapter' reproduces chapter commands; an attempt to lower below
4670 `subsubsection' reproduces subsubsection commands. Also, lowered
4671 subsubsections and raised chapters will not work with
4672 @command{makeinfo}'s feature of implicitly determining node pointers,
4673 since the menu structure won't be correct.
4674
4675 Write each @code{@@raisesections} and @code{@@lowersections} command
4676 on a line of its own.
4677
4678
4679 @node Nodes
4680 @chapter Nodes
4681
4682 @dfn{Nodes} are the primary segments of a Texinfo file. They do not
4683 in and of themselves impose a hierarchical or any other kind of
4684 structure on a file. Nodes contain @dfn{node pointers} that name
4685 other nodes, and can contain @dfn{menus} which are lists of nodes. In
4686 Info, the movement commands can carry you to a pointed-to node or to a
4687 node listed in a menu.
4688
4689 Node pointers and menus provide structure for Info files just as
4690 chapters, sections, subsections, and the like, provide structure for
4691 printed books.
4692
4693 Because node names are used in cross-references, it is not desirable
4694 to casually change them. Such name changes invalidate references from
4695 other manuals, from mail archives, and so on.
4696
4697 @menu
4698 * Two Paths:: Different commands to structure
4699 Info output and printed output.
4700 * Node Menu Illustration:: A diagram, and sample nodes and menus.
4701 * node:: Creating nodes, in detail.
4702 * makeinfo Pointer Creation:: Letting makeinfo determine node pointers.
4703 * anchor:: Defining arbitrary cross-reference targets.
4704 @end menu
4705
4706
4707 @node Two Paths
4708 @section Two Paths
4709
4710 The node and menu commands and the chapter structuring commands are
4711 technically independent of each other:
4712
4713 @itemize @bullet
4714 @item
4715 In Info, node and menu commands provide structure. The chapter
4716 structuring commands generate headings with different kinds of
4717 underlining---asterisks for chapters, hyphens for sections, and so on;
4718 they do nothing else.@refill
4719
4720 @item
4721 In @TeX{}, the chapter structuring commands generate chapter and section
4722 numbers and tables of contents. The node and menu commands provide
4723 information for cross references; they do nothing else.@refill
4724 @end itemize
4725
4726 You can use node pointers and menus to structure an Info file any way
4727 you want; and you can write a Texinfo file so that its Info output has a
4728 different structure than its printed output. However, virtually all
4729 Texinfo files are written such that the structure for the Info output
4730 corresponds to the structure for the printed output. It is neither
4731 convenient nor understandable to the reader to do otherwise.@refill
4732
4733 Generally, printed output is structured in a tree-like hierarchy in
4734 which the chapters are the major limbs from which the sections branch
4735 out. Similarly, node pointers and menus are organized to create a
4736 matching structure in the Info output.@refill
4737
4738
4739 @node Node Menu Illustration
4740 @section Node and Menu Illustration
4741
4742 Here is a copy of the diagram shown earlier that illustrates a Texinfo
4743 file with three chapters, each of which contains two sections.@refill
4744
4745 The ``root'' is at the top of the diagram and the ``leaves'' are at the
4746 bottom. This is how such a diagram is drawn conventionally; it
4747 illustrates an upside-down tree. For this reason, the root node is
4748 called the `Top' node, and `Up' node pointers carry you closer to the
4749 root.@refill
4750
4751 @example
4752 @group
4753 Top
4754 |
4755 -------------------------------------
4756 | | |
4757 Chapter 1 Chapter 2 Chapter 3
4758 | | |
4759 -------- -------- --------
4760 | | | | | |
4761 Section Section Section Section Section Section
4762 1.1 1.2 2.1 2.2 3.1 3.2
4763 @end group
4764 @end example
4765
4766 The fully-written command to start Chapter 2 would be this:
4767
4768 @example
4769 @group
4770 @@node Chapter 2, Chapter 3, Chapter 1, Top
4771 @@comment node-name, next, previous, up
4772 @end group
4773 @end example
4774
4775 @noindent
4776 This @code{@@node} line says that the name of this node is ``Chapter
4777 2'', the name of the `Next' node is ``Chapter 3'', the name of the
4778 `Previous' node is ``Chapter 1'', and the name of the `Up' node is
4779 ``Top''. You can omit writing out these node names if your document is
4780 hierarchically organized (@pxref{makeinfo Pointer Creation}), but the
4781 pointer relationships still obtain.
4782
4783 @quotation Note
4784 @strong{Please Note:} `Next' refers to the next node at the same
4785 hierarchical level in the manual, not necessarily to the next node
4786 within the Texinfo file. In the Texinfo file, the subsequent node may
4787 be at a lower level---a section-level node most often follows a
4788 chapter-level node, for example. `Next' and `Previous' refer to nodes
4789 at the @emph{same} hierarchical level. (The `Top' node contains the
4790 exception to this rule. Since the `Top' node is the only node at that
4791 level, `Next' refers to the first following node, which is almost always
4792 a chapter or chapter-level node.)@refill
4793 @end quotation
4794
4795 To go to Sections 2.1 and 2.2 using Info, you need a menu inside Chapter
4796 2. (@xref{Menus}.) You would write the menu just
4797 before the beginning of Section 2.1, like this:@refill
4798
4799 @example
4800 @group
4801 @@menu
4802 * Sect. 2.1:: Description of this section.
4803 * Sect. 2.2::
4804 @@end menu
4805 @end group
4806 @end example
4807
4808 Write the node for Sect. 2.1 like this:@refill
4809
4810 @example
4811 @group
4812 @@node Sect. 2.1, Sect. 2.2, Chapter 2, Chapter 2
4813 @@comment node-name, next, previous, up
4814 @end group
4815 @end example
4816
4817 In Info format, the `Next' and `Previous' pointers of a node usually
4818 lead to other nodes at the same level---from chapter to chapter or from
4819 section to section (sometimes, as shown, the `Previous' pointer points
4820 up); an `Up' pointer usually leads to a node at the level above (closer
4821 to the `Top' node); and a `Menu' leads to nodes at a level below (closer
4822 to `leaves'). (A cross reference can point to a node at any level;
4823 see @ref{Cross References}.)@refill
4824
4825 Usually, an @code{@@node} command and a chapter structuring command are
4826 used in sequence, along with indexing commands. (You may follow the
4827 @code{@@node} line with a comment line that reminds you which pointer is
4828 which.)@refill
4829
4830 Here is the beginning of the chapter in this manual called ``Ending a
4831 Texinfo File''. This shows an @code{@@node} line followed by a comment
4832 line, an @code{@@chapter} line, and then by indexing lines.@refill
4833
4834 @example
4835 @group
4836 @@node Ending a File, Structuring, Beginning a File, Top
4837 @@comment node-name, next, previous, up
4838 @@chapter Ending a Texinfo File
4839 @@cindex Ending a Texinfo file
4840 @@cindex Texinfo file ending
4841 @@cindex File ending
4842 @end group
4843 @end example
4844
4845
4846 @node node
4847 @section The @code{@@node} Command
4848
4849 @cindex Node, defined
4850 @findex node
4851
4852 A @dfn{node} is a segment of text that begins at an @code{@@node}
4853 command and continues until the next @code{@@node} command. The
4854 definition of node is different from that for chapter or section. A
4855 chapter may contain sections and a section may contain subsections;
4856 but a node cannot contain subnodes; the text of a node continues only
4857 until the next @code{@@node} command in the file. A node usually
4858 contains only one chapter structuring command, the one that follows
4859 the @code{@@node} line. On the other hand, in printed output nodes
4860 are used only for cross references, so a chapter or section may
4861 contain any number of nodes. Indeed, a chapter usually contains
4862 several nodes, one for each section, subsection, and
4863 subsubsection.
4864
4865 To specify a node, write an @code{@@node} command at the beginning of
4866 a line, and follow it with up to four arguments, separated by commas,
4867 on the rest of the same line. The first argument is required; it is
4868 the name of this node (for details of node names, @pxref{Node Line
4869 Requirements}). The subsequent arguments are the names of the `Next',
4870 `Previous', and `Up' pointers, in that order, and may be omitted if
4871 your Texinfo document is hierarchically organized (@pxref{makeinfo
4872 Pointer Creation}).
4873
4874 @opindex accesskey@r{, in HTML output}
4875 Whether the node pointers are specified implicitly or explicitly, the
4876 HTML output from @command{makeinfo} for each node includes links to
4877 the `Next', `Previous', and `Up' nodes. The HTML also uses the
4878 @code{accesskey} attribute with the values @samp{n}, @samp{p}, and
4879 @samp{u} respectively. This allows people using web browsers to
4880 follow the nagivation using (typically) @kbd{M-@var{letter}}, e.g.,
4881 @kbd{M-n} for the `Next' node, from anywhere within the node.
4882
4883 You may insert spaces before each name on the @code{@@node} line if
4884 you wish; the spaces are ignored. You must write the name of the node
4885 and (if present) the names of the `Next', `Previous', and `Up'
4886 pointers all on the same line. Otherwise, the formatters fail.
4887 (@inforef{Top, info, info}, for more information about nodes in Info.)
4888
4889 Usually, you write one of the chapter-structuring command lines
4890 immediately after an @code{@@node} line---for example, an
4891 @code{@@section} or @code{@@subsection} line. (@xref{Structuring
4892 Command Types}.)
4893
4894 @TeX{} uses @code{@@node} lines to identify the names to use for cross
4895 references. For this reason, you must write @code{@@node} lines in a
4896 Texinfo file that you intend to format for printing, even if you do not
4897 intend to format it for Info. (Cross references, such as the one at the
4898 end of this sentence, are made with @code{@@xref} and related commands;
4899 see @ref{Cross References}.)
4900
4901 @menu
4902 * Node Names:: How to choose node and pointer names.
4903 * Writing a Node:: How to write an @code{@@node} line.
4904 * Node Line Tips:: Keep names short.
4905 * Node Line Requirements:: Keep names unique, without @@-commands.
4906 * First Node:: How to write a `Top' node.
4907 * makeinfo top command:: How to use the @code{@@top} command.
4908 @end menu
4909
4910
4911 @node Node Names
4912 @subsection Choosing Node and Pointer Names
4913
4914 @cindex Node names, choosing
4915 The name of a node identifies the node (for details of node names,
4916 @pxref{Node Line Requirements}). The pointers enable you to reach
4917 other nodes and consist simply of the names of those nodes.
4918
4919 Normally, a node's `Up' pointer contains the name of the node whose
4920 menu mentions that node. The node's `Next' pointer contains the name
4921 of the node that follows the present node in that menu and its
4922 `Previous' pointer contains the name of the node that precedes it in
4923 that menu. When a node's `Previous' node is the same as its `Up'
4924 node, both node pointers name the same node.
4925
4926 Usually, the first node of a Texinfo file is the `Top' node, and its
4927 `Up' and `Previous' pointers point to the @file{dir} file, which
4928 contains the main menu for all of Info.
4929
4930 The `Top' node itself contains the main or master menu for the manual.
4931 Also, it is helpful to include a brief description of the manual in the
4932 `Top' node. @xref{First Node}, for information on how to write the
4933 first node of a Texinfo file.
4934
4935 Even when you explicitly specify all pointers, that does not mean you
4936 can write the nodes in the Texinfo source file in an arbitrary order!
4937 Because @TeX{} processes the file sequentially, irrespective of node
4938 pointers, you must write the nodes in the order you wish them to appear
4939 in the output.
4940
4941
4942 @node Writing a Node
4943 @subsection How to Write an @code{@@node} Line
4944 @cindex Writing an @code{@@node} line
4945 @cindex @code{@@node} line writing
4946 @cindex Node line writing
4947
4948 The easiest way to write an @code{@@node} line is to write @code{@@node}
4949 at the beginning of a line and then the name of the node, like
4950 this:
4951
4952 @example
4953 @@node @var{node-name}
4954 @end example
4955
4956 If you are using XEmacs, you can use the update node commands
4957 provided by Texinfo mode to insert the names of the pointers; or you
4958 can leave the pointers out of the Texinfo file and let @code{makeinfo}
4959 insert node pointers into the Info file it creates. (@xref{Texinfo
4960 Mode}, and @ref{makeinfo Pointer Creation}.)
4961
4962 Alternatively, you can insert the `Next', `Previous', and `Up'
4963 pointers yourself. If you do this, you may find it helpful to use the
4964 Texinfo mode keyboard command @kbd{C-c C-c n}. This command inserts
4965 @samp{@@node} and a comment line listing the names of the pointers in
4966 their proper order. The comment line helps you keep track of which
4967 arguments are for which pointers. This comment line is especially useful
4968 if you are not familiar with Texinfo.
4969
4970 The template for a fully-written-out node line with `Next', `Previous',
4971 and `Up' pointers looks like this:
4972
4973 @example
4974 @@node @var{node-name}, @var{next}, @var{previous}, @var{up}
4975 @end example
4976
4977 The @var{node-name} argument must be present, but the others are
4978 optional. If you wish to specify some but not others, just insert
4979 commas as needed, as in: @samp{@@node mynode,,,uppernode}. However,
4980 we recommend leaving off all the pointers and letting @code{makeinfo}
4981 determine them, as described above.
4982
4983 If you wish, you can ignore @code{@@node} lines altogether in your first
4984 draft and then use the @code{texinfo-insert-node-lines} command to
4985 create @code{@@node} lines for you. However, we do not recommend this
4986 practice. It is better to name the node itself at the same time that
4987 you write a segment so you can easily make cross references. A large
4988 number of cross references are an especially important feature of a good
4989 Info file.
4990
4991 After you have inserted an @code{@@node} line, you should immediately
4992 write an @@-command for the chapter or section and insert its name.
4993 Next (and this is important!), put in several index entries. Usually,
4994 you will find at least two and often as many as four or five ways of
4995 referring to the node in the index. Use them all. This will make it
4996 much easier for people to find the node.
4997
4998
4999 @node Node Line Tips
5000 @subsection @code{@@node} Line Tips
5001
5002 Here are three suggestions:
5003
5004 @itemize @bullet
5005 @item
5006 Try to pick node names that are informative but short.@refill
5007
5008 In the Info file, the file name, node name, and pointer names are all
5009 inserted on one line, which may run into the right edge of the window.
5010 (This does not cause a problem with Info, but is ugly.)@refill
5011
5012 @item
5013 Try to pick node names that differ from each other near the beginnings
5014 of their names. This way, it is easy to use automatic name completion in
5015 Info.@refill
5016
5017 @item
5018 By convention, node names are capitalized just as they would be for
5019 section or chapter titles---initial and significant words are
5020 capitalized; others are not.@refill
5021 @end itemize
5022
5023
5024 @node Node Line Requirements
5025 @subsection @code{@@node} Line Requirements
5026
5027 @cindex Node line requirements
5028 @cindex Restrictions on node names
5029 Here are several requirements for @code{@@node} lines:
5030
5031 @itemize @bullet
5032 @cindex Unique nodename requirement
5033 @cindex Node name must be unique
5034 @item
5035 All the node names for a single Info file must be unique.
5036
5037 Duplicates confuse the Info movement commands. This means, for
5038 example, that if you end every chapter with a summary, you must name
5039 each summary node differently. You cannot just call each one
5040 ``Summary''. You may, however, duplicate the titles of chapters, sections,
5041 and the like. Thus you can end each chapter in a book with a section
5042 called ``Summary'', so long as the node names for those sections are all
5043 different.
5044
5045 @item
5046 A pointer name must be the name of a node.
5047
5048 The node to which a pointer points may come before or after the
5049 node containing the pointer.
5050
5051 @cindex @@-commands in nodename
5052 @cindex Node name, should not contain @@-commands
5053 @item
5054 @@-commands in node names are not allowed. This includes punctuation
5055 characters that are escaped with a @samp{@@}, such as @code{@@} and
5056 @code{@{}, and accent commands such as @samp{@@'}. (For a few cases
5057 when this is useful, Texinfo has limited support for using
5058 @w{@@-commands} in node names; see @ref{Pointer Validation}.) Perhaps
5059 this limitation will be removed some day.
5060
5061 @item
5062 @cindex Colon in nodename
5063 @cindex Comma in nodename
5064 @cindex Parentheses in nodename
5065 @cindex Period in nodename
5066 @cindex Characters, invalid in node name
5067 @cindex Invalid characters in node names
5068 @cindex Node names, invalid characters in
5069 Unfortunately, you cannot use periods, commas, colons or parentheses
5070 within a node name; these confuse the Texinfo processors. Perhaps
5071 this limitation will be removed some day, too.
5072
5073 @need 700
5074 For example, the following is a section title in this manual:
5075
5076 @smallexample
5077 @@code@{@@@@unnumberedsec@}, @@code@{@@@@appendixsec@}, @@code@{@@@@heading@}
5078 @end smallexample
5079
5080 @noindent
5081 But the corresponding node name lacks the commas and the @@'s:
5082
5083 @smallexample
5084 unnumberedsec appendixsec heading
5085 @end smallexample
5086
5087 @cindex Case in node name
5088 @item
5089 Case is significant in node names.
5090
5091 @cindex White space in node name
5092 @cindex Spaces in node name
5093 Spaces before and after names on the @samp{@@node} line are ignored,
5094 but spaces ``inside'' a name are significant. For example:
5095
5096 @example
5097 @@node foo bar,
5098 @@node foo bar ,
5099 @@node foo bar ,
5100 @end example
5101
5102 @noindent all define the same node, @samp{foo bar}. References to the
5103 node should all use that name, without the leading or trailing spaces,
5104 but with the internal spaces.
5105 @end itemize
5106
5107
5108 @node First Node
5109 @subsection The First Node
5110 @cindex Top node is first
5111 @cindex First node
5112
5113 The first node of a Texinfo file is the @dfn{Top} node, except in an
5114 included file (@pxref{Include Files}). The Top node should contain a
5115 short summary, copying permissions, and a master menu. @xref{The Top
5116 Node}, for more information on the Top node contents and examples.
5117
5118 Here is a description of the node pointers to be used in the Top node:
5119
5120 @itemize @bullet
5121
5122 @item
5123 @cindex Up node of Top node
5124 @cindex (dir) as Up node of Top node
5125 The Top node (which must be named @samp{top} or @samp{Top}) should have
5126 as its `Up' node the name of a node in another file, where there is a
5127 menu that leads to this file. Specify the file name in parentheses.
5128
5129 Usually, all Info files are installed in the same Info directory tree;
5130 in this case, use @samp{(dir)} as the parent of the Top node; this is
5131 short for @samp{(dir)top}, and specifies the Top node in the @file{dir}
5132 file, which contains the main menu for the Info system as a whole.
5133
5134 @item
5135 @cindex Prev node of Top node
5136 The `Prev' node of the Top node should also be your @samp{(dir)} file.
5137
5138 @item
5139 @cindex Next node of Top node
5140 The `Next' node of the Top node should be the first chapter in your
5141 document.
5142
5143 @end itemize
5144
5145 @xref{Installing an Info File}, for more information about installing
5146 an Info file in the @file{info} directory.
5147
5148 It is usually best to leave the pointers off entirely and let the
5149 tools implicitly define them, with this simple result:
5150
5151 @example
5152 @@node Top
5153 @end example
5154
5155
5156 @node makeinfo top command
5157 @subsection The @code{@@top} Sectioning Command
5158 @findex top @r{(@@-command)}
5159
5160 A special sectioning command, @code{@@top} should be used with the
5161 @code{@@node Top} line. The @code{@@top} sectioning command tells
5162 @code{makeinfo} that it marks the `Top' node in the file. It provides
5163 the information that @code{makeinfo} needs to insert node pointers
5164 automatically. Write the @code{@@top} command at the beginning of the
5165 line immediately following the @code{@@node Top} line. Write the title
5166 on the remaining part of the same line as the @code{@@top} command.
5167
5168 In Info, the @code{@@top} sectioning command causes the title to appear
5169 on a line by itself, with a line of asterisks inserted underneath, as
5170 other sectioning commands do.
5171
5172 In @TeX{} and @code{texinfo-format-buffer}, the @code{@@top}
5173 sectioning command is merely a synonym for @code{@@unnumbered}.
5174 Neither of these formatters require an @code{@@top} command, and do
5175 nothing special with it. You can use @code{@@chapter} or
5176 @code{@@unnumbered} after the @code{@@node Top} line when you use
5177 these formatters. Also, you can use @code{@@chapter} or
5178 @code{@@unnumbered} when you use the Texinfo updating commands to
5179 create or update pointers and menus.
5180
5181 Thus, in practice, a Top node starts like this:
5182
5183 @example
5184 @@node Top
5185 @@top Your Manual Title
5186 @end example
5187
5188
5189 @node makeinfo Pointer Creation
5190 @section Creating Pointers with @code{makeinfo}
5191 @cindex Creating pointers with @code{makeinfo}
5192 @cindex Pointer creation with @code{makeinfo}
5193 @cindex Automatic pointer creation with @code{makeinfo}
5194
5195 The @code{makeinfo} program has a feature for automatically
5196 determining node pointers for a hierarchically organized document. We
5197 highly recommend using it.
5198
5199 When you take advantage of this feature, you do not need to write the
5200 `Next', `Previous', and `Up' pointers after the name of a node.
5201 However, you must write a sectioning command, such as @code{@@chapter}
5202 or @code{@@section}, on the line immediately following each truncated
5203 @code{@@node} line (except that comment lines may intervene).
5204
5205 In addition, you must follow the `Top' @code{@@node} line with a line
5206 beginning with @code{@@top} to mark the `Top' node in the
5207 file. @xref{makeinfo top, , @code{@@top}}.
5208
5209 Finally, you must write the name of each node (except for the `Top'
5210 node) in a menu that is one or more hierarchical levels above the
5211 node's hierarchical level.
5212
5213 @cindex Detail menu
5214 @findex detailmenu
5215 If you use a detailed menu in your master menu (@pxref{Master Menu
5216 Parts}), mark it with the @code{@@detailmenu @@dots@{@} @@end
5217 detailmenu} environment, or @command{makeinfo} will get confused,
5218 typically about the last and/or first node in the document.
5219
5220 This implicit node pointer creation feature in @code{makeinfo}
5221 relieves you from the need to update menus and pointers manually or
5222 with Texinfo mode commands. (@xref{Updating Nodes and Menus}.)
5223
5224 In most cases, you will want to take advantage of this feature and not
5225 redundantly specify node pointers. However, Texinfo documents are not
5226 required to be organized hierarchically or in fact to contain
5227 sectioning commands at all (for example, if you never intend the
5228 document to be printed). The special procedure for handling the short
5229 text before a menu (@pxref{Menus}) also disables this
5230 feature, for that group of nodes. In those cases, you will need to
5231 explicitly specify all pointers.
5232
5233 @node anchor
5234 @section @code{@@anchor}: Defining Arbitrary Cross-reference Targets
5235
5236 @findex anchor
5237 @cindex Anchors
5238 @cindex Cross-reference targets, arbitrary
5239 @cindex Targets for cross-references, arbitrary
5240
5241 An @dfn{anchor} is a position in your document, labeled so that
5242 cross-references can refer to it, just as they can to nodes. You create
5243 an anchor with the @code{@@anchor} command, and give the label as a
5244 normal brace-delimited argument. For example:
5245
5246 @example
5247 This marks the @@anchor@{x-spot@}spot.
5248 @dots{}
5249 @@xref@{x-spot,,the spot@}.
5250 @end example
5251
5252 @noindent produces:
5253
5254 @example
5255 This marks the spot.
5256 @dots{}
5257 See [the spot], page 1.
5258 @end example
5259
5260 As you can see, the @code{@@anchor} command itself produces no output.
5261 This example defines an anchor `x-spot' just before the word `spot'.
5262 You can refer to it later with an @code{@@xref} or other cross-reference
5263 command, as shown. @xref{Cross References}, for details on the
5264 cross-reference commands.
5265
5266 It is best to put @code{@@anchor} commands just before the position you
5267 wish to refer to; that way, the reader's eye is led on to the correct
5268 text when they jump to the anchor. You can put the @code{@@anchor}
5269 command on a line by itself if that helps readability of the source.
5270 Whitespace (including newlines) is ignored after @code{@@anchor}.
5271
5272 Anchor names and node names may not conflict. Anchors and nodes are
5273 given similar treatment in some ways; for example, the @code{goto-node}
5274 command in standalone Info takes either an anchor name or a node name as
5275 an argument. (@xref{goto-node,,,info-stnd,GNU Info}.)
5276
5277 Also like node names, anchor names cannot include some characters
5278 (@pxref{Node Line Requirements}).
5279
5280
5281 @node Menus
5282 @chapter Menus
5283 @cindex Menus
5284 @findex menu
5285
5286 @dfn{Menus} contain pointers to subordinate nodes. In online output,
5287 you use menus to go to such nodes. Menus have no effect in printed
5288 manuals and do not appear in them.
5289
5290 A node with a menu should not contain much text. If you find yourself
5291 writing a lot of text before a menu, we generally recommend moving
5292 most of the text into a new subnode---all but a paragraph or two.
5293 Otherwise, a reader with a terminal that displays only a few lines may
5294 miss the menu and its associated text. As a practical matter, it is
5295 best to locate a menu within 20 or so lines of the beginning of the
5296 node.
5297
5298 @menu
5299 * Menu Location:: Menus go at the ends of short nodes.
5300 * Writing a Menu:: What is a menu?
5301 * Menu Parts:: A menu entry has three parts.
5302 * Less Cluttered Menu Entry:: Two part menu entry.
5303 * Menu Example:: Two and three part menu entries.
5304 * Other Info Files:: How to refer to a different Info file.
5305 @end menu
5306
5307
5308 @node Menu Location
5309 @section Menu Location
5310 @cindex Menu location
5311 @cindex Location of menus
5312
5313 A menu must be located at the end of a node, without any regular text
5314 or additional commands between the @code{@@end menu} and the beginning
5315 of the next node. (As a consequence, there may be at most one menu in
5316 a node.)
5317
5318 @cindex Info format, and menus
5319 This is actually a useful restriction, since a reader who uses the
5320 menu could easily miss any such text. Technically, it is necessary
5321 because in Info format, there is no marker for the end of a menu, so
5322 Info-reading programs would have no way to know when the menu ends and
5323 normal text resumes.
5324
5325 @cindex Hierarchical documents, and menus
5326 Technically, menus can carry you to any node, regardless of the
5327 structure of the document; even to nodes in a different Info file.
5328 However, we do not recommend ever making use of this, because the
5329 @command{makeinfo} implicit pointer creation feature (@pxref{makeinfo
5330 Pointer Creation}) and XEmacs Texinfo mode updating commands work
5331 only to create menus of subordinate nodes in a hierarchically
5332 structured document. Instead, use cross references to refer to
5333 arbitrary nodes.
5334
5335 In the past, we recommended using a @samp{@@heading} command within an
5336 @code{@@ifinfo} conditional instead of the normal sectioning commands
5337 after a very short node with a menu. This had the advantage of making
5338 the printed output look better, because there was no very short text
5339 between two headings on the page. But this also does not work with
5340 @command{makeinfo}'s implicit pointer creation, and it also makes the
5341 XML output incorrect, since it does not reflect the true document
5342 structure. So, regrettably, we can no longer recommend this.
5343
5344
5345 @node Writing a Menu
5346 @section Writing a Menu
5347 @cindex Writing a menu
5348 @cindex Menu writing
5349
5350 A menu consists of an @code{@@menu} command on a line by itself
5351 followed by menu entry lines or menu comment lines and then by an
5352 @code{@@end menu} command on a line by itself.
5353
5354 A menu looks like this:
5355
5356 @example
5357 @group
5358 @@menu
5359 Larger Units of Text
5360
5361 * Files:: All about handling files.
5362 * Multiples: Buffers. Multiple buffers; editing
5363 several files at once.
5364 @@end menu
5365 @end group
5366 @end example
5367
5368 In a menu, every line that begins with an @w{@samp{* }} is a @dfn{menu
5369 entry}. (Note the space after the asterisk.) A line that does not
5370 start with an @w{@samp{* }} may also appear in a menu. Such a line is
5371 not a menu entry but is a menu comment line that appears in the Info
5372 file. In the example above, the line @samp{Larger Units of Text} is a
5373 menu comment line; the two lines starting with @w{@samp{* }} are menu
5374 @cindex Spaces, in menus
5375 entries. Space characters in a menu are preserved as-is; this allows
5376 you to format the menu as you wish.
5377
5378 @opindex accesskey@r{, in HTML output}
5379 In the HTML output from @command{makeinfo}, the @code{accesskey}
5380 attribute is used with the values @samp{1}@dots{}@samp{9} for the
5381 first nine entries. This allows people using web browsers to follow
5382 the first menu entries using (typically) @kbd{M-@var{digit}}, e.g.,
5383 @kbd{M-1} for the first entry.
5384
5385
5386 @node Menu Parts
5387 @section The Parts of a Menu
5388 @cindex Parts of a menu
5389 @cindex Menu parts
5390 @cindex @code{@@menu} parts
5391
5392 A menu entry has three parts, only the second of which is required:
5393
5394 @enumerate
5395 @item
5396 The menu entry name (optional).
5397
5398 @item
5399 The name of the node (required).
5400
5401 @item
5402 A description of the item (optional).
5403 @end enumerate
5404
5405 The template for a generic menu entry looks like this (but see the
5406 next section for one more possibility):
5407
5408 @example
5409 * @var{menu-entry-name}: @var{node-name}. @var{description}
5410 @end example
5411
5412 Follow the menu entry name with a single colon and follow the node name
5413 with tab, comma, newline, or the two characters period and space
5414 (@samp{. }).
5415
5416 In Info, a user selects a node with the @kbd{m} (@code{Info-menu})
5417 command. The menu entry name is what the user types after the @kbd{m}
5418 command.
5419
5420 The third part of a menu entry is a descriptive phrase or sentence.
5421 Menu entry names and node names are often short; the description
5422 explains to the reader what the node is about. A useful description
5423 complements the node name rather than repeats it. The description,
5424 which is optional, can spread over two or more lines; if it does, some
5425 authors prefer to indent the second line while others prefer to align it
5426 with the first (and all others). It's up to you.
5427
5428
5429 @node Less Cluttered Menu Entry
5430 @section Less Cluttered Menu Entry
5431 @cindex Two part menu entry
5432 @cindex Double-colon menu entries
5433 @cindex Menu entries with two colons
5434 @cindex Less cluttered menu entry
5435 @cindex Uncluttered menu entry
5436
5437 When the menu entry name and node name are the same, you can write
5438 the name immediately after the asterisk and space at the beginning of
5439 the line and follow the name with two colons.
5440
5441 @need 800
5442 For example, write
5443
5444 @example
5445 * Name:: @var{description}
5446 @end example
5447
5448 @need 800
5449 @noindent
5450 instead of
5451
5452 @example
5453 * Name: Name. @var{description}
5454 @end example
5455
5456 You should indeed use the node name for the menu entry name whenever
5457 possible, since it reduces visual clutter in the menu.
5458
5459
5460 @node Menu Example
5461 @section A Menu Example
5462 @cindex Menu example
5463 @cindex Example menu
5464
5465 A menu looks like this in Texinfo:@refill
5466
5467 @example
5468 @group
5469 @@menu
5470 * menu entry name: Node name. A short description.
5471 * Node name:: This form is preferred.
5472 @@end menu
5473 @end group
5474 @end example
5475
5476 @need 800
5477 @noindent
5478 This produces:
5479
5480 @example
5481 @group
5482 * menu:
5483
5484 * menu entry name: Node name. A short description.
5485 * Node name:: This form is preferred.
5486 @end group
5487 @end example
5488
5489 @need 700
5490 Here is an example as you might see it in a Texinfo file:@refill
5491
5492 @example
5493 @group
5494 @@menu
5495 Larger Units of Text
5496
5497 * Files:: All about handling files.
5498 * Multiples: Buffers. Multiple buffers; editing
5499 several files at once.
5500 @@end menu
5501 @end group
5502 @end example
5503
5504 @need 800
5505 @noindent
5506 This produces:
5507
5508 @example
5509 @group
5510 * menu:
5511 Larger Units of Text
5512
5513 * Files:: All about handling files.
5514 * Multiples: Buffers. Multiple buffers; editing
5515 several files at once.
5516 @end group
5517 @end example
5518
5519 In this example, the menu has two entries. @samp{Files} is both a menu
5520 entry name and the name of the node referred to by that name.
5521 @samp{Multiples} is the menu entry name; it refers to the node named
5522 @samp{Buffers}. The line @samp{Larger Units of Text} is a comment; it
5523 appears in the menu, but is not an entry.@refill
5524
5525 Since no file name is specified with either @samp{Files} or
5526 @samp{Buffers}, they must be the names of nodes in the same Info file
5527 (@pxref{Other Info Files, , Referring to Other Info Files}).@refill
5528
5529 @node Other Info Files
5530 @comment node-name, next, previous, up
5531 @section Referring to Other Info Files
5532 @cindex Referring to other Info files
5533 @cindex Nodes in other Info files
5534 @cindex Other Info files' nodes
5535 @cindex Going to other Info files' nodes
5536 @cindex Info; other files' nodes
5537
5538 You can create a menu entry that enables a reader in Info to go to a
5539 node in another Info file by writing the file name in parentheses just
5540 before the node name. In this case, you should use the three-part menu
5541 entry format, which saves the reader from having to type the file
5542 name.@refill
5543
5544 @need 800
5545 The format looks like this:@refill
5546
5547 @example
5548 @group
5549 @@menu
5550 * @var{first-entry-name}:(@var{filename})@var{nodename}. @var{description}
5551 * @var{second-entry-name}:(@var{filename})@var{second-node}. @var{description}
5552 @@end menu
5553 @end group
5554 @end example
5555
5556 For example, to refer directly to the @samp{Outlining} and
5557 @samp{Rebinding} nodes in the @cite{XEmacs User's Manual}, you would
5558 write a menu like this:@refill
5559
5560 @example
5561 @group
5562 @@menu
5563 * Outlining: (xemacs)Outline Mode. The major mode for
5564 editing outlines.
5565 * Rebinding: (xemacs)Rebinding. How to redefine the
5566 meaning of a key.
5567 @@end menu
5568 @end group
5569 @end example
5570
5571 If you do not list the node name, but only name the file, then Info
5572 presumes that you are referring to the `Top' node.@refill
5573
5574 The @file{dir} file that contains the main menu for Info has menu
5575 entries that list only file names. These take you directly to the `Top'
5576 nodes of each Info document. (@xref{Installing an Info File}.)
5577
5578 @need 700
5579 For example:
5580
5581 @example
5582 @group
5583 * Info: (info). Documentation browsing system.
5584 * XEmacs: (xemacs). The extensible, self-documenting
5585 text editor.
5586 @end group
5587 @end example
5588
5589 @noindent
5590 (The @file{dir} top level directory for the Info system is an Info file,
5591 not a Texinfo file, but a menu entry looks the same in both types of
5592 file.)@refill
5593
5594 The XEmacs Texinfo mode menu updating commands only work with nodes
5595 within the current buffer, so you cannot use them to create menus that
5596 refer to other files. You must write such menus by hand.
5597
5598
5599 @node Cross References
5600 @chapter Cross References
5601 @cindex Making cross references
5602 @cindex Cross references
5603 @cindex References
5604
5605 @dfn{Cross references} are used to refer the reader to other parts of the
5606 same or different Texinfo files. In Texinfo, nodes and anchors are the
5607 places to which cross references can refer.
5608
5609 @menu
5610 * References:: What cross references are for.
5611 * Cross Reference Commands:: A summary of the different commands.
5612 * Cross Reference Parts:: A cross reference has several parts.
5613 * xref:: Begin a reference with `See' @dots{}
5614 * Top Node Naming:: How to refer to the beginning of another file.
5615 * ref:: A reference for the last part of a sentence.
5616 * pxref:: How to write a parenthetical cross reference.
5617 * inforef:: How to refer to an Info-only file.
5618 * uref:: How to refer to a uniform resource locator.
5619 * cite:: How to refer to books not in the Info system.
5620 @end menu
5621
5622 @node References
5623 @section What References Are For
5624
5625 Often, but not always, a printed document should be designed so that
5626 it can be read sequentially. People tire of flipping back and forth
5627 to find information that should be presented to them as they need
5628 it.@refill
5629
5630 However, in any document, some information will be too detailed for
5631 the current context, or incidental to it; use cross references to
5632 provide access to such information. Also, an online help system or a
5633 reference manual is not like a novel; few read such documents in
5634 sequence from beginning to end. Instead, people look up what they
5635 need. For this reason, such creations should contain many cross
5636 references to help readers find other information that they may not
5637 have read.@refill
5638
5639 In a printed manual, a cross reference results in a page reference,
5640 unless it is to another manual altogether, in which case the cross
5641 reference names that manual.@refill
5642
5643 In Info, a cross reference results in an entry that you can follow
5644 using the Info @samp{f} command. (@inforef{Help-Xref, Following
5645 cross-references, info}.)
5646
5647 The various cross reference commands use nodes (or anchors,
5648 @pxref{anchor,,@code{@@anchor}}) to define cross reference locations.
5649 This is evident in Info, in which a cross reference takes you to the
5650 specified location. @TeX{} also uses nodes to define cross reference
5651 locations, but the action is less obvious. When @TeX{} generates a DVI
5652 file, it records each node's page number and uses the page numbers in making
5653 references. Thus, if you are writing a manual that will only be
5654 printed, and will not be used online, you must nonetheless write
5655 @code{@@node} lines to name the places to which you make cross
5656 references.@refill
5657
5658 @need 800
5659 @node Cross Reference Commands
5660 @comment node-name, next, previous, up
5661 @section Different Cross Reference Commands
5662 @cindex Different cross reference commands
5663
5664 There are four different cross reference commands:@refill
5665
5666 @table @code
5667 @item @@xref
5668 Used to start a sentence in the printed manual saying @w{`See @dots{}'}
5669 or an Info cross-reference saying @samp{*Note @var{name}: @var{node}.}.
5670
5671 @item @@ref
5672 Used within or, more often, at the end of a sentence; same as
5673 @code{@@xref} for Info; produces just the reference in the printed
5674 manual without a preceding `See'.@refill
5675
5676 @item @@pxref
5677 Used within parentheses to make a reference that suits both an Info
5678 file and a printed book. Starts with a lower case `see' within the
5679 printed manual. (@samp{p} is for `parenthesis'.)@refill
5680
5681 @item @@inforef
5682 Used to make a reference to an Info file for which there is no printed
5683 manual.@refill
5684 @end table
5685
5686 @noindent
5687 (The @code{@@cite} command is used to make references to books and
5688 manuals for which there is no corresponding Info file and, therefore,
5689 no node to which to point. @xref{cite, , @code{@@cite}}.)@refill
5690
5691 @node Cross Reference Parts
5692 @comment node-name, next, previous, up
5693 @section Parts of a Cross Reference
5694 @cindex Cross reference parts
5695 @cindex Parts of a cross reference
5696
5697 A cross reference command requires only one argument, which is the
5698 name of the node to which it refers. But a cross reference command
5699 may contain up to four additional arguments. By using these
5700 arguments, you can provide a cross reference name for Info, a topic
5701 description or section title for the printed output, the name of a
5702 different Info file, and the name of a different printed
5703 manual.@refill
5704
5705 Here is a simple cross reference example:@refill
5706
5707 @example
5708 @@xref@{Node name@}.
5709 @end example
5710
5711 @noindent
5712 which produces
5713
5714 @example
5715 *Note Node name::.
5716 @end example
5717
5718 @noindent
5719 and
5720
5721 @quotation
5722 See Section @var{nnn} [Node name], page @var{ppp}.
5723 @end quotation
5724
5725 @need 700
5726 Here is an example of a full five-part cross reference:@refill
5727
5728 @example
5729 @group
5730 @@xref@{Node name, Cross Reference Name, Particular Topic,
5731 info-file-name, A Printed Manual@}, for details.
5732 @end group
5733 @end example
5734
5735 @noindent
5736 which produces
5737
5738 @example
5739 *Note Cross Reference Name: (info-file-name)Node name,
5740 for details.
5741 @end example
5742
5743 @noindent
5744 in Info and
5745
5746 @quotation
5747 See section ``Particular Topic'' in @i{A Printed Manual}, for details.
5748 @end quotation
5749
5750 @noindent
5751 in a printed book.
5752
5753 The five possible arguments for a cross reference are:@refill
5754
5755 @enumerate
5756 @item
5757 The node or anchor name (required). This is the location to which the
5758 cross reference takes you. In a printed document, the location of the
5759 node provides the page reference only for references within the same
5760 document.@refill
5761
5762 @item
5763 The cross reference name for the Info reference, if it is to be
5764 different from the node name or the topic description. If you
5765 include this argument, it becomes the first part of the cross reference.
5766 It is usually omitted; then the topic description (third argument) is
5767 used if it was specified; if that was omitted as well, the node name
5768 is used.
5769
5770 @item
5771 A topic description or section name. Often, this is the title of the
5772 section. This is used as the name of the reference in the printed
5773 manual. If omitted, the node name is used.@refill
5774
5775 @item
5776 The name of the Info file in which the reference is located, if it is
5777 different from the current file. You need not include any @samp{.info}
5778 suffix on the file name, since Info readers try appending it
5779 automatically.
5780
5781 @item
5782 The name of a printed manual from a different Texinfo file.@refill
5783 @end enumerate
5784
5785 The template for a full five argument cross reference looks like
5786 this:@refill
5787
5788 @example
5789 @group
5790 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
5791 @var{info-file-name}, @var{printed-manual-title}@}.
5792 @end group
5793 @end example
5794
5795 Cross references with one, two, three, four, and five arguments are
5796 described separately following the description of @code{@@xref}.@refill
5797
5798 Write a node name in a cross reference in exactly the same way as in
5799 the @code{@@node} line, including the same capitalization; otherwise, the
5800 formatters may not find the reference.@refill
5801
5802 You can write cross reference commands within a paragraph, but note
5803 how Info and @TeX{} format the output of each of the various commands:
5804 write @code{@@xref} at the beginning of a sentence; write
5805 @code{@@pxref} only within parentheses, and so on.@refill
5806
5807 @node xref
5808 @comment node-name, next, previous, up
5809 @section @code{@@xref}
5810 @findex xref
5811 @cindex Cross references using @code{@@xref}
5812 @cindex References using @code{@@xref}
5813
5814 The @code{@@xref} command generates a cross reference for the
5815 beginning of a sentence. The Info formatting commands convert it into
5816 an Info cross reference, which the Info @samp{f} command can use to
5817 bring you directly to another node. The @TeX{} typesetting commands
5818 convert it into a page reference, or a reference to another book or
5819 manual.@refill
5820
5821 @menu
5822 * Reference Syntax:: What a reference looks like and requires.
5823 * One Argument:: @code{@@xref} with one argument.
5824 * Two Arguments:: @code{@@xref} with two arguments.
5825 * Three Arguments:: @code{@@xref} with three arguments.
5826 * Four and Five Arguments:: @code{@@xref} with four and five arguments.
5827 @end menu
5828
5829 @node Reference Syntax
5830 @subsection What a Reference Looks Like and Requires
5831
5832 Most often, an Info cross reference looks like this:@refill
5833
5834 @example
5835 *Note @var{node-name}::.
5836 @end example
5837
5838 @noindent
5839 or like this
5840
5841 @example
5842 *Note @var{cross-reference-name}: @var{node-name}.
5843 @end example
5844
5845 @noindent
5846 In @TeX{}, a cross reference looks like this:
5847
5848 @quotation
5849 See Section @var{section-number} [@var{node-name}], page @var{page}.
5850 @end quotation
5851
5852 @noindent
5853 or like this
5854
5855 @quotation
5856 See Section @var{section-number} [@var{title-or-topic}], page @var{page}.
5857 @end quotation
5858
5859 The @code{@@xref} command does not generate a period or comma to end
5860 the cross reference in either the Info file or the printed output.
5861 You must write that period or comma yourself; otherwise, Info will not
5862 recognize the end of the reference. (The @code{@@pxref} command works
5863 differently. @xref{pxref, , @code{@@pxref}}.)@refill
5864
5865 @quotation Caution
5866 A period or comma @strong{must} follow the closing
5867 brace of an @code{@@xref}. It is required to terminate the cross
5868 reference. This period or comma will appear in the output, both in
5869 the Info file and in the printed manual.@refill
5870 @end quotation
5871
5872 @code{@@xref} must refer to an Info node by name. Use @code{@@node}
5873 to define the node (@pxref{Writing a Node}).@refill
5874
5875 @code{@@xref} is followed by several arguments inside braces, separated by
5876 commas. Whitespace before and after these commas is ignored.@refill
5877
5878 A cross reference requires only the name of a node; but it may contain
5879 up to four additional arguments. Each of these variations produces a
5880 cross reference that looks somewhat different.@refill
5881
5882 @quotation Note
5883 Commas separate arguments in a cross reference;
5884 avoid including them in the title or other part lest the formatters
5885 mistake them for separators.@refill
5886 @end quotation
5887
5888 @node One Argument
5889 @subsection @code{@@xref} with One Argument
5890
5891 The simplest form of @code{@@xref} takes one argument, the name of
5892 another node in the same Info file. The Info formatters produce
5893 output that the Info readers can use to jump to the reference; @TeX{}
5894 produces output that specifies the page and section number for you.@refill
5895
5896 @need 700
5897 @noindent
5898 For example,
5899
5900 @example
5901 @@xref@{Tropical Storms@}.
5902 @end example
5903
5904 @noindent
5905 produces
5906
5907 @example
5908 *Note Tropical Storms::.
5909 @end example
5910
5911 @noindent
5912 and
5913
5914 @quotation
5915 See Section 3.1 [Tropical Storms], page 24.
5916 @end quotation
5917
5918 @noindent
5919 (Note that in the preceding example the closing brace is followed by a
5920 period.)@refill
5921
5922 You can write a clause after the cross reference, like this:@refill
5923
5924 @example
5925 @@xref@{Tropical Storms@}, for more info.
5926 @end example
5927
5928 @noindent
5929 which produces
5930
5931 @example
5932 *Note Tropical Storms::, for more info.
5933 @end example
5934
5935 @noindent
5936 and
5937
5938 @quotation
5939 See Section 3.1 [Tropical Storms], page 24, for more info.
5940 @end quotation
5941
5942 @noindent
5943 (Note that in the preceding example the closing brace is followed by a
5944 comma, and then by the clause, which is followed by a period.)@refill
5945
5946 @node Two Arguments
5947 @subsection @code{@@xref} with Two Arguments
5948
5949 With two arguments, the second is used as the name of the Info cross
5950 reference, while the first is still the name of the node to which the
5951 cross reference points.@refill
5952
5953 @need 750
5954 @noindent
5955 The template is like this:
5956
5957 @example
5958 @@xref@{@var{node-name}, @var{cross-reference-name}@}.
5959 @end example
5960
5961 @need 700
5962 @noindent
5963 For example,
5964
5965 @example
5966 @@xref@{Electrical Effects, Lightning@}.
5967 @end example
5968
5969 @noindent
5970 produces:
5971
5972 @example
5973 *Note Lightning: Electrical Effects.
5974 @end example
5975
5976 @noindent
5977 and
5978
5979 @quotation
5980 See Section 5.2 [Electrical Effects], page 57.
5981 @end quotation
5982
5983 @noindent
5984 (Note that in the preceding example the closing brace is followed by a
5985 period; and that the node name is printed, not the cross reference name.)
5986
5987 You can write a clause after the cross reference, like this:@refill
5988
5989 @example
5990 @@xref@{Electrical Effects, Lightning@}, for more info.
5991 @end example
5992
5993 @noindent
5994 which produces
5995 @example
5996 *Note Lightning: Electrical Effects, for more info.
5997 @end example
5998
5999 @noindent
6000 and
6001
6002 @quotation
6003 See Section 5.2 [Electrical Effects], page 57, for more info.
6004 @end quotation
6005
6006 @noindent
6007 (Note that in the preceding example the closing brace is followed by a
6008 comma, and then by the clause, which is followed by a period.)@refill
6009
6010 @node Three Arguments
6011 @subsection @code{@@xref} with Three Arguments
6012
6013 A third argument replaces the node name in the @TeX{} output. The third
6014 argument should be the name of the section in the printed output, or
6015 else state the topic discussed by that section. Often, you will want to
6016 use initial upper case letters so it will be easier to read when the
6017 reference is printed. Use a third argument when the node name is
6018 unsuitable because of syntax or meaning.@refill
6019
6020 Remember to avoid placing a comma within the title or topic section of
6021 a cross reference, or within any other section. The formatters divide
6022 cross references into arguments according to the commas; a comma
6023 within a title or other section will divide it into two arguments. In
6024 a reference, you need to write a title such as ``Clouds, Mist, and
6025 Fog'' without the commas.@refill
6026
6027 Also, remember to write a comma or period after the closing brace of an
6028 @code{@@xref} to terminate the cross reference. In the following
6029 examples, a clause follows a terminating comma.@refill
6030
6031
6032 @need 750
6033 @noindent
6034 The template is like this:
6035
6036 @example
6037 @group
6038 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic}@}.
6039 @end group
6040 @end example
6041
6042 @need 700
6043 @noindent
6044 For example,
6045
6046 @example
6047 @group
6048 @@xref@{Electrical Effects, Lightning, Thunder and Lightning@},
6049 for details.
6050 @end group
6051 @end example
6052
6053 @noindent
6054 produces
6055
6056 @example
6057 *Note Lightning: Electrical Effects, for details.
6058 @end example
6059
6060 @noindent
6061 and
6062
6063 @quotation
6064 See Section 5.2 [Thunder and Lightning], page 57, for details.
6065 @end quotation
6066
6067 If a third argument is given and the second one is empty, then the
6068 third argument serves both. (Note how two commas, side by side, mark
6069 the empty second argument.)@refill
6070
6071 @example
6072 @group
6073 @@xref@{Electrical Effects, , Thunder and Lightning@},
6074 for details.
6075 @end group
6076 @end example
6077
6078 @noindent
6079 produces
6080
6081 @example
6082 *Note Thunder and Lightning: Electrical Effects, for details.
6083 @end example
6084
6085 @noindent
6086 and
6087
6088 @quotation
6089 See Section 5.2 [Thunder and Lightning], page 57, for details.
6090 @end quotation
6091
6092 As a practical matter, it is often best to write cross references with
6093 just the first argument if the node name and the section title are the
6094 same, and with the first and third arguments if the node name and title
6095 are different.@refill
6096
6097 Here are several examples from @cite{The GNU Awk User's Guide}:@refill
6098
6099 @smallexample
6100 @@xref@{Sample Program@}.
6101 @@xref@{Glossary@}.
6102 @@xref@{Case-sensitivity, ,Case-sensitivity in Matching@}.
6103 @@xref@{Close Output, , Closing Output Files and Pipes@},
6104 for more information.
6105 @@xref@{Regexp, , Regular Expressions as Patterns@}.
6106 @end smallexample
6107
6108 @node Four and Five Arguments
6109 @subsection @code{@@xref} with Four and Five Arguments
6110
6111 In a cross reference, a fourth argument specifies the name of another
6112 Info file, different from the file in which the reference appears, and
6113 a fifth argument specifies its title as a printed manual.@refill
6114
6115 Remember that a comma or period must follow the closing brace of an
6116 @code{@@xref} command to terminate the cross reference. In the
6117 following examples, a clause follows a terminating comma.@refill
6118
6119 @need 800
6120 @noindent
6121 The template is:
6122
6123 @example
6124 @group
6125 @@xref@{@var{node-name}, @var{cross-reference-name}, @var{title-or-topic},
6126 @var{info-file-name}, @var{printed-manual-title}@}.
6127 @end group
6128 @end example
6129
6130 @need 700
6131 @noindent
6132 For example,
6133
6134 @example
6135 @@xref@{Electrical Effects, Lightning, Thunder and Lightning,
6136 weather, An Introduction to Meteorology@}, for details.
6137 @end example
6138
6139 @noindent
6140 produces
6141
6142 @example
6143 *Note Lightning: (weather)Electrical Effects, for details.
6144 @end example
6145
6146 @noindent
6147 The name of the Info file is enclosed in parentheses and precedes
6148 the name of the node.
6149
6150 @noindent
6151 In a printed manual, the reference looks like this:@refill
6152
6153 @quotation
6154 See section ``Thunder and Lightning'' in @i{An Introduction to
6155 Meteorology}, for details.
6156 @end quotation
6157
6158 @noindent
6159 The title of the printed manual is typeset in italics; and the
6160 reference lacks a page number since @TeX{} cannot know to which page a
6161 reference refers when that reference is to another manual.@refill
6162
6163 Often, you will leave out the second argument when you use the long
6164 version of @code{@@xref}. In this case, the third argument, the topic
6165 description, will be used as the cross reference name in Info.@refill
6166
6167 @noindent
6168 The template looks like this:
6169
6170 @example
6171 @@xref@{@var{node-name}, , @var{title-or-topic}, @var{info-file-name},
6172 @var{printed-manual-title}@}, for details.
6173 @end example
6174
6175 @noindent
6176 which produces
6177
6178 @example
6179 *Note @var{title-or-topic}: (@var{info-file-name})@var{node-name}, for details.
6180 @end example
6181
6182 @noindent
6183 and
6184
6185 @quotation
6186 See section @var{title-or-topic} in @var{printed-manual-title}, for details.
6187 @end quotation
6188
6189 @need 700
6190 @noindent
6191 For example,
6192
6193 @example
6194 @@xref@{Electrical Effects, , Thunder and Lightning,
6195 weather, An Introduction to Meteorology@}, for details.
6196 @end example
6197
6198 @noindent
6199 produces
6200
6201 @example
6202 @group
6203 *Note Thunder and Lightning: (weather)Electrical Effects,
6204 for details.
6205 @end group
6206 @end example
6207
6208 @noindent
6209 and
6210
6211 @quotation
6212 See section ``Thunder and Lightning'' in @i{An Introduction to
6213 Meteorology}, for details.
6214 @end quotation
6215
6216 On rare occasions, you may want to refer to another Info file that
6217 is within a single printed manual---when multiple Texinfo files are
6218 incorporated into the same @TeX{} run but make separate Info files.
6219 In this case, you need to specify only the fourth argument, and not
6220 the fifth.@refill
6221
6222 @node Top Node Naming
6223 @section Naming a `Top' Node
6224 @cindex Naming a `Top' Node in references
6225 @cindex @samp{@r{Top}} node naming for references
6226
6227 In a cross reference, you must always name a node. This means that in
6228 order to refer to a whole manual, you must identify the `Top' node by
6229 writing it as the first argument to the @code{@@xref} command. (This
6230 is different from the way you write a menu entry; see @ref{Other Info
6231 Files, , Referring to Other Info Files}.) At the same time, to
6232 provide a meaningful section topic or title in the printed cross
6233 reference (instead of the word `Top'), you must write an appropriate
6234 entry for the third argument to the @code{@@xref} command.
6235 @refill
6236
6237 @noindent
6238 Thus, to make a cross reference to @cite{The GNU Make Manual},
6239 write:@refill
6240
6241 @example
6242 @@xref@{Top, , Overview, make, The GNU Make Manual@}.
6243 @end example
6244
6245 @noindent
6246 which produces
6247
6248 @example
6249 *Note Overview: (make)Top.
6250 @end example
6251
6252 @noindent
6253 and
6254
6255 @quotation
6256 See section ``Overview'' in @i{The GNU Make Manual}.
6257 @end quotation
6258
6259 @noindent
6260 In this example, @samp{Top} is the name of the first node, and
6261 @samp{Overview} is the name of the first section of the manual.
6262
6263
6264 @node ref
6265 @section @code{@@ref}
6266 @cindex Cross references using @code{@@ref}
6267 @cindex References using @code{@@ref}
6268 @findex ref
6269
6270 @code{@@ref} is nearly the same as @code{@@xref} except that it does
6271 not generate a `See' in the printed output, just the reference itself.
6272 This makes it useful as the last part of a sentence.
6273
6274 @noindent For example,
6275
6276 @cindex Hurricanes
6277 @example
6278 For more information, @@pxref@{This@}, and @@ref@{That@}.
6279 @end example
6280
6281 @noindent produces in Info:
6282
6283 @example
6284 For more information, *note This::, and *note That::.
6285 @end example
6286
6287 @noindent and in printed output:
6288
6289 @quotation
6290 For more information, see Section 1.1 [This], page 1,
6291 and Section 1.2 [That], page 2.
6292 @end quotation
6293
6294 The @code{@@ref} command sometimes tempts writers to express
6295 themselves in a manner that is suitable for a printed manual but looks
6296 awkward in the Info format. Bear in mind that your audience will be
6297 using both the printed and the Info format. For example:
6298
6299 @cindex Sea surges
6300 @example
6301 Sea surges are described in @@ref@{Hurricanes@}.
6302 @end example
6303
6304 @noindent looks ok in the printed output:
6305
6306 @quotation
6307 Sea surges are described in Section 6.7 [Hurricanes], page 72.
6308 @end quotation
6309
6310 @noindent but is awkward to read in Info, ``note'' being a verb:
6311
6312 @example
6313 Sea surges are described in *note Hurricanes::.
6314 @end example
6315
6316 You should write a period or comma immediately after an @code{@@ref}
6317 command with two or more arguments. If there is no such following
6318 punctuation, @command{makeinfo} will generate a (grammatically
6319 incorrect) period in the Info output; otherwise, the cross-reference
6320 would fail completely, due to the current syntax of Info format.
6321
6322 In general, it is best to use @code{@@ref} only when you need some
6323 word other than ``see'' to precede the reference. When ``see'' (or
6324 ``See'') is ok, @code{@@xref} and @code{@@pxref} are preferable.
6325
6326
6327 @node pxref
6328 @section @code{@@pxref}
6329 @cindex Cross references using @code{@@pxref}
6330 @cindex References using @code{@@pxref}
6331 @findex pxref
6332
6333 The parenthetical reference command, @code{@@pxref}, is nearly the
6334 same as @code{@@xref}, but it is best used at the end of a sentence or
6335 before a closing parenthesis. The command differs from @code{@@xref}
6336 in two ways:
6337
6338 @enumerate
6339 @item
6340 @TeX{} typesets the reference for the printed manual with a lower case
6341 `see' rather than an upper case `See'.
6342
6343 @item
6344 The Info formatting commands automatically end the reference with a
6345 closing colon or period, if necessary.
6346 @end enumerate
6347
6348 @code{@@pxref} is designed so that the output looks right and works
6349 right at the end of a sentence or parenthetical phrase, both in
6350 printed output and in an Info file. In a printed manual, a closing
6351 comma or period should not follow a cross reference within
6352 parentheses; such punctuation is wrong. But in an Info file, suitable
6353 closing punctuation must follow the cross reference so Info can
6354 recognize its end. @code{@@pxref} spares you the need to use
6355 complicated methods to put a terminator into one form of the output
6356 and not the other.
6357
6358 @noindent
6359 With one argument, a parenthetical cross reference looks like this:
6360
6361 @cindex Flooding
6362 @example
6363 @dots{} storms cause flooding (@@pxref@{Hurricanes@}) @dots{}
6364 @end example
6365
6366 @need 800
6367 @noindent
6368 which produces
6369
6370 @example
6371 @group
6372 @dots{} storms cause flooding (*note Hurricanes::) @dots{}
6373 @end group
6374 @end example
6375
6376 @noindent
6377 and
6378
6379 @quotation
6380 @dots{} storms cause flooding (see Section 6.7 [Hurricanes], page 72) @dots{}
6381 @end quotation
6382
6383 With two arguments, a parenthetical cross reference has this template:
6384
6385 @example
6386 @dots{} (@@pxref@{@var{node-name}, @var{cross-reference-name}@}) @dots{}
6387 @end example
6388
6389 @noindent
6390 which produces
6391
6392 @example
6393 @dots{} (*note @var{cross-reference-name}: @var{node-name}.) @dots{}
6394 @end example
6395
6396 @noindent
6397 and
6398
6399 @quotation
6400 @dots{} (see Section @var{nnn} [@var{node-name}], page @var{ppp}) @dots{}
6401 @end quotation
6402
6403 @code{@@pxref} can be used with up to five arguments, just like
6404 @code{@@xref} (@pxref{xref, , @code{@@xref}}).
6405
6406 In past versions of Texinfo, it was not allowed to write punctuation
6407 after a @code{@@pxref}, so it could be used @emph{only} before a right
6408 parenthesis. This is no longer the case, so now it can be used (for
6409 example) at the end of a sentence, where a lowercase ``see'' works
6410 best. For instance:
6411
6412 @example
6413 @dots{} For more information, @@pxref@{More@}.
6414 @end example
6415
6416 @noindent
6417 which outputs (in Info):
6418
6419 @example
6420 @dots{} For more information, *note More::.
6421 @end example
6422
6423 @noindent
6424 This works fine. @code{@@pxref} should only be followed by a comma,
6425 period, or right parenthesis; in other cases, @command{makeinfo} has
6426 to insert a period to make the cross-reference work correctly in Info,
6427 and that period looks wrong.
6428
6429 As a matter of general style, @code{@@pxref} is best used at the ends
6430 of sentences. Although it technically works in the middle of a
6431 sentence, that location breaks up the flow of reading.
6432
6433
6434 @node inforef
6435 @section @code{@@inforef}
6436 @cindex Cross references using @code{@@inforef}
6437 @cindex References using @code{@@inforef}
6438 @findex inforef
6439
6440 @code{@@inforef} is used for making cross references to Info
6441 documents---even from a printed manual. This might be because you
6442 want to refer to conditional @code{@@ifinfo} text
6443 (@pxref{Conditionals}), or because printed output is not available
6444 (perhaps because there is no Texinfo source), among other
6445 possibilities.
6446
6447 The command takes either two or three arguments, in the following
6448 order:@refill
6449
6450 @enumerate
6451 @item
6452 The node name.
6453
6454 @item
6455 The cross reference name (optional).
6456
6457 @item
6458 The Info file name.
6459 @end enumerate
6460
6461 @noindent
6462 Separate the arguments with commas, as with @code{@@xref}. Also, you
6463 must terminate the reference with a comma or period after the
6464 @samp{@}}, as you do with @code{@@xref}.@refill
6465
6466 @noindent
6467 The template is:
6468
6469 @example
6470 @@inforef@{@var{node-name}, @var{cross-reference-name}, @var{info-file-name}@},
6471 @end example
6472
6473 @need 800
6474 @noindent
6475 For example,
6476
6477 @example
6478 @group
6479 @@inforef@{Advanced, Advanced Info commands, info@},
6480 for more information.
6481 @end group
6482 @end example
6483
6484 @need 800
6485 @noindent
6486 produces (in Info):
6487
6488 @example
6489 @group
6490 *Note Advanced Info commands: (info)Advanced,
6491 for more information.
6492 @end group
6493 @end example
6494
6495 @need 800
6496 @noindent
6497 and (in the printed output):
6498
6499 @quotation
6500 See Info file @file{info}, node @samp{Advanced}, for more information.
6501 @end quotation
6502
6503 (This particular example is not realistic, since the Info manual is
6504 written in Texinfo, so all formats are available.)
6505
6506 The converse of @code{@@inforef} is @code{@@cite}, which is used to
6507 refer to printed works for which no Info form exists. @xref{cite, ,
6508 @code{@@cite}}.
6509
6510
6511 @node uref
6512 @section @code{@@url}, @code{@@uref@{@var{url}[, @var{text}][, @var{replacement}]@}}
6513 @findex uref
6514 @cindex Uniform resource locator, referring to
6515 @cindex URL, referring to
6516
6517 @cindex @code{href}, producing HTML
6518 @code{@@uref} produces a reference to a uniform resource locator (url).
6519 It takes one mandatory argument, the url, and two optional arguments
6520 which control the text that is displayed. In HTML output, @code{@@uref}
6521 produces a link you can follow.
6522
6523 @code{@@url} is a synonym for @code{@@uref}. Originally, @code{@@url}
6524 had the meaning of @code{@@indicateurl}
6525 (@pxref{indicateurl,,@code{@@indicateurl}}), but in actual practice it
6526 was misused the vast majority of the time. So we've changed the
6527 meaning.
6528
6529 The second argument, if specified, is the text to display (the default
6530 is the url itself); in Info and DVI output, but not in HTML output, the
6531 url is also output.
6532
6533 @cindex Man page, reference to
6534 The third argument, if specified, is the text to display, but in this
6535 case the url is @emph{not} output in any format. This is useful when
6536 the text is already sufficiently referential, as in a man page. If
6537 the third argument is given, the second argument is ignored.
6538
6539 If the url is long enough to cause problems with line breaking, you
6540 may find it useful to insert @code{@@/} at places where a line break
6541 would be acceptable (after @samp{/} characters, for instance). This
6542 tells @TeX{} to allow (but not force) a line break at those places.
6543 @xref{Line Breaks}.
6544
6545 Here is an example of the simple one argument form, where the url is
6546 both the target and the text of the link:
6547
6548 @example
6549 The official GNU ftp site is @@uref@{ftp://ftp.gnu.org/gnu@}.
6550 @end example
6551
6552 @noindent produces:
6553 @display
6554 The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
6555 @end display
6556
6557
6558 An example of the two-argument form:
6559 @example
6560 The official @@uref@{ftp://ftp.gnu.org/gnu, GNU ftp site@}
6561 holds programs and texts.
6562 @end example
6563
6564 @noindent produces:
6565 @display
6566 The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
6567 holds programs and texts.
6568 @end display
6569
6570 @noindent that is, the Info output is this:
6571 @example
6572 The official GNU ftp site (ftp://ftp.gnu.org/gnu)
6573 holds programs and texts.
6574 @end example
6575
6576 @noindent and the HTML output is this:
6577 @example
6578 The official <a href="ftp://ftp.gnu.org/gnu">GNU ftp site</a>
6579 holds programs and texts.
6580 @end example
6581
6582
6583 An example of the three-argument form:
6584 @example
6585 The @@uref@{/man.cgi/1/ls,,ls@} program @dots{}
6586 @end example
6587
6588 @noindent produces:
6589 @display
6590 The @uref{/man.cgi/1/ls,,ls} program @dots{}
6591 @end display
6592
6593 @noindent but with HTML:
6594 @example
6595 The <a href="/man.cgi/1/ls">ls</a> program @dots{}
6596 @end example
6597
6598 To merely indicate a url without creating a link people can follow, use
6599 @code{@@indicateurl} (@pxref{indicateurl, @code{@@indicateurl}}).
6600
6601 Some people prefer to display url's in the unambiguous format:
6602
6603 @display
6604 <URL:http://@var{host}/@var{path}>
6605 @end display
6606
6607 @noindent
6608 @cindex <URL: convention, not used
6609 You can use this form in the input file if you wish. We feel it's not
6610 necessary to include the @samp{<URL:} and @samp{>} in the output,
6611 since any software that tries to detect url's in text already has to
6612 detect them without the @samp{<URL:} to be useful.
6613
6614
6615 @node cite
6616 @section @code{@@cite}@{@var{reference}@}
6617 @findex cite
6618
6619 Use the @code{@@cite} command for the name of a book that lacks a
6620 companion Info file. The command produces italics in the printed
6621 manual, and quotation marks in the Info file.
6622
6623 If a book is written in Texinfo, it is better to use a cross reference
6624 command since a reader can easily follow such a reference in Info.
6625 @xref{xref, , @code{@@xref}}.
6626
6627
6628 @node Marking Text
6629 @chapter Marking Words and Phrases
6630 @cindex Paragraph, marking text within
6631 @cindex Marking words and phrases
6632 @cindex Words and phrases, marking them
6633 @cindex Marking text within a paragraph
6634 @cindex Text, marking up
6635
6636 In Texinfo, you can mark words and phrases in a variety of ways.
6637 The Texinfo formatters use this information to determine how to
6638 highlight the text.
6639 You can specify, for example, whether a word or phrase is a
6640 defining occurrence, a metasyntactic variable, or a symbol used in a
6641 program. Also, you can emphasize text, in several different ways.
6642
6643 @menu
6644 * Indicating:: How to indicate definitions, files, etc.
6645 * Emphasis:: How to emphasize text.
6646 @end menu
6647
6648
6649 @node Indicating
6650 @section Indicating Definitions, Commands, etc.
6651 @cindex Highlighting text
6652 @cindex Indicating commands, definitions, etc.
6653
6654 Texinfo has commands for indicating just what kind of object a piece of
6655 text refers to. For example, metasyntactic variables are marked by
6656 @code{@@var}, and code by @code{@@code}. Since the pieces of text are
6657 labelled by commands that tell what kind of object they are, it is easy
6658 to change the way the Texinfo formatters prepare such text. (Texinfo is
6659 an @emph{intentional} formatting language rather than a @emph{typesetting}
6660 formatting language.)@refill
6661
6662 For example, in a printed manual,
6663 code is usually illustrated in a typewriter font;
6664 @code{@@code} tells @TeX{} to typeset this text in this font. But it
6665 would be easy to change the way @TeX{} highlights code to use another
6666 font, and this change would not affect how keystroke examples are
6667 highlighted. If straight typesetting commands were used in the body
6668 of the file and you wanted to make a change, you would need to check
6669 every single occurrence to make sure that you were changing code and
6670 not something else that should not be changed.@refill
6671
6672 @menu
6673 * Useful Highlighting:: Highlighting provides useful information.
6674 * code:: Indicating program code.
6675 * kbd:: Showing keyboard input.
6676 * key:: Specifying keys.
6677 * samp:: Indicating a literal sequence of characters.
6678 * verb:: Indicating a verbatim sequence of characters.
6679 * var:: Indicating metasyntactic variables.
6680 * env:: Indicating environment variables.
6681 * file:: Indicating file names.
6682 * command:: Indicating command names.
6683 * option:: Indicating option names.
6684 * dfn:: Specifying definitions.
6685 * abbr:: Indicating abbreviations.
6686 * acronym:: Indicating acronyms.
6687 * indicateurl:: Indicating an example URL.
6688 * email:: Indicating an electronic mail address.
6689 @end menu
6690
6691
6692 @node Useful Highlighting
6693 @subsection Highlighting Commands are Useful
6694
6695 The highlighting commands can be used to extract useful information
6696 from the file, such as lists of functions or file names. It is
6697 possible, for example, to write a program in XEmacs Lisp (or a keyboard
6698 macro) to insert an index entry after every paragraph that contains
6699 words or phrases marked by a specified command. You could do this to
6700 construct an index of functions if you had not already made the
6701 entries.@refill
6702
6703 The commands serve a variety of purposes:@refill
6704
6705 @table @code
6706 @item @@code@{@var{sample-code}@}
6707 Indicate text that is a literal example of a piece of a program.
6708 @xref{code,,@code{@@code}}.
6709
6710 @item @@kbd@{@var{keyboard-characters}@}
6711 Indicate keyboard input.
6712 @xref{kbd,,@code{@@kbd}}.
6713
6714 @item @@key@{@var{key-name}@}
6715 Indicate the conventional name for a key on a keyboard.
6716 @xref{key,,@code{@@key}}.
6717
6718 @item @@samp@{@var{text}@}
6719 Indicate text that is a literal example of a sequence of characters.
6720 @xref{samp,,@code{@@samp}}.
6721
6722 @item @@verb@{@var{text}@}
6723 Write a verbatim sequence of characters.
6724 @xref{verb,,@code{@@verb}}.
6725
6726 @item @@var@{@var{metasyntactic-variable}@}
6727 Indicate a metasyntactic variable.
6728 @xref{var,,@code{@@var}}.
6729
6730 @item @@env@{@var{environment-variable}@}
6731 Indicate an environment variable.
6732 @xref{env,,@code{@@env}}.
6733
6734 @item @@file@{@var{file-name}@}
6735 Indicate the name of a file.
6736 @xref{file,,@code{@@file}}.
6737
6738 @item @@command@{@var{command-name}@}
6739 Indicate the name of a command.
6740 @xref{command,,@code{@@command}}.
6741
6742 @item @@option@{@var{option}@}
6743 Indicate a command-line option.
6744 @xref{option,,@code{@@option}}.
6745
6746 @item @@dfn@{@var{term}@}
6747 Indicate the introductory or defining use of a term.
6748 @xref{dfn,,@code{@@dfn}}.
6749
6750 @item @@cite@{@var{reference}@}
6751 Indicate the name of a book.
6752 @xref{cite,,@code{@@cite}}.
6753
6754 @item @@abbr@{@var{abbreviation}@}
6755 Indicate an abbreviation, such as `Comput.'.
6756
6757 @item @@acronym@{@var{acronym}@}
6758 Indicate an acronym.
6759 @xref{acronym,,@code{@@acronym}}.
6760
6761 @item @@indicateurl@{@var{uniform-resource-locator}@}
6762 Indicate an example (that is, nonfunctional) uniform resource locator.
6763 @xref{indicateurl,,@code{@@indicateurl}}. (Use @code{@@url}
6764 (@pxref{uref,,@code{@@url}}) for live url's.)
6765
6766 @item @@email@{@var{email-address}[, @var{displayed-text}]@}
6767 Indicate an electronic mail address.
6768 @xref{email,,@code{@@email}}.
6769
6770 @ignore
6771 @item @@ctrl@{@var{ctrl-char}@}
6772 Use for an ASCII control character.
6773 @end ignore
6774 @end table
6775
6776
6777 @node code
6778 @subsection @code{@@code}@{@var{sample-code}@}
6779 @findex code
6780
6781 @cindex Syntactic tokens, indicating
6782 Use the @code{@@code} command to indicate text that is a piece of a
6783 program and which consists of entire syntactic tokens. Enclose the
6784 text in braces.
6785
6786 @cindex Expressions in a program, indicating
6787 @cindex Keywords, indicating
6788 @cindex Reserved words, indicating
6789 Thus, you should use @code{@@code} for an expression in a program, for
6790 the name of a variable or function used in a program, or for a
6791 keyword in a programming language.
6792
6793 Use @code{@@code} for command names in languages that resemble
6794 programming languages, such as Texinfo. For example, @code{@@code} and
6795 @code{@@samp} are produced by writing @samp{@@code@{@@@@code@}} and
6796 @samp{@@code@{@@@@samp@}} in the Texinfo source, respectively.
6797
6798 @cindex Case, not altering in @code{@@code}
6799 It is incorrect to alter the case of a word inside an @code{@@code}
6800 command when it appears at the beginning of a sentence. Most computer
6801 languages are case sensitive. In C, for example, @code{Printf} is
6802 different from the identifier @code{printf}, and most likely is a
6803 misspelling of it. Even in languages which are not case sensitive, it
6804 is confusing to a human reader to see identifiers spelled in different
6805 ways. Pick one spelling and always use that. If you do not want to
6806 start a sentence with a command name written all in lower case, you
6807 should rearrange the sentence.
6808
6809 In the printed manual, @code{@@code} causes @TeX{} to typeset the
6810 argument in a typewriter face. In the Info file, it causes the Info
6811 formatting commands to use single quotation marks around the text.
6812 For example,
6813
6814 @example
6815 The function returns @@code@{nil@}.
6816 @end example
6817
6818 @noindent
6819 produces this:
6820
6821 @quotation
6822 The function returns @code{nil}.
6823 @end quotation
6824
6825 @iftex
6826 @noindent
6827 and this in the Info file:
6828 @example
6829 The function returns `nil'.
6830 @end example
6831 @end iftex
6832
6833 Here are some cases for which it is preferable @emph{not} to use @code{@@code}:
6834
6835 @itemize @bullet
6836 @item
6837 For shell command names such as @command{ls} (use @code{@@command}).
6838
6839 @item
6840 For shell options such as @samp{-c} when such options stand alone (use
6841 @code{@@option}).
6842
6843 @item
6844 Also, an entire shell command often looks better if written using
6845 @code{@@samp} rather than @code{@@code}. In this case, the rule is to
6846 choose the more pleasing format.
6847
6848 @item
6849 For environment variable such as @env{TEXINPUTS} (use @code{@@env}).
6850
6851 @item
6852 For a string of characters shorter than a syntactic token. For example,
6853 if you are writing about @samp{goto-ch}, which is just a part of the
6854 name for the @code{goto-char} XEmacs Lisp function, you should use
6855 @code{@@samp}.
6856
6857 @item
6858 In general, when writing about the characters used in a token; for
6859 example, do not use @code{@@code} when you are explaining what letters
6860 or printable symbols can be used in the names of functions. (Use
6861 @code{@@samp}.) Also, you should not use @code{@@code} to mark text
6862 that is considered input to programs unless the input is written in a
6863 language that is like a programming language. For example, you should
6864 not use @code{@@code} for the keystroke commands of XEmacs (use
6865 @code{@@kbd} instead) although you may use @code{@@code} for the names
6866 of the XEmacs Lisp functions that the keystroke commands invoke.
6867
6868 @end itemize
6869
6870 Since @code{@@command}, @code{@@option}, and @code{@@env} were
6871 introduced relatively recently, it is acceptable to use @code{@@code} or
6872 @code{@@samp} for command names, options, and environment variables.
6873 The new commands allow you to express the markup more precisely, but
6874 there is no real harm in using the older commands, and of course the
6875 long-standing manuals do so.
6876
6877 Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
6878 @samp{_} characters within @code{@@code} and related commands. This
6879 can be controlled with @code{@@allowcodebreaks}
6880 (@pxref{allowcodebreaks,,@code{@@allowcodebreaks}}).
6881
6882
6883 @node kbd
6884 @subsection @code{@@kbd}@{@var{keyboard-characters}@}
6885 @findex kbd
6886 @cindex Keyboard input
6887
6888 Use the @code{@@kbd} command for characters of input to be typed by
6889 users. For example, to refer to the characters @kbd{M-a}, write:
6890
6891 @example
6892 @@kbd@{M-a@}
6893 @end example
6894
6895 @noindent
6896 and to refer to the characters @kbd{M-x shell}, write:
6897
6898 @example
6899 @@kbd@{M-x shell@}
6900 @end example
6901
6902 @cindex User input
6903 @cindex Slanted typewriter font, for @code{@@kbd}
6904 By default, the @code{@@kbd} command produces a different font
6905 (slanted typewriter instead of normal typewriter) in the printed
6906 manual, so users can distinguish the characters that they are supposed
6907 to type from those that the computer outputs.
6908
6909 In Info output, @code{@@kbd} is usually the same as @code{@@code},
6910 producing `quotes' around its argument. However, in typewriter-like
6911 contexts such as the @code{@@example} environment (@pxref{example})
6912 and @code{@@code} command itself, the quotes are omitted, since Info
6913 format cannot use distinguishing fonts.
6914
6915 @findex kbdinputstyle
6916 Since the usage of @code{@@kbd} varies from manual to manual, you can
6917 control the font switching with the @code{@@kbdinputstyle} command.
6918 This command has no effect on Info output. Write this command at the
6919 beginning of a line with a single word as an argument, one of the
6920 following:
6921
6922 @vindex distinct@r{, value for @code{@@kbdinputstyle}}
6923 @vindex example@r{, value for @code{@@kbdinputstyle}}
6924 @vindex code@r{, value for @code{@@kbdinputstyle}}
6925 @table @samp
6926 @item code
6927 Always use the same font for @code{@@kbd} as @code{@@code}.
6928 @item example
6929 Use the distinguishing font for @code{@@kbd} only in @code{@@example}
6930 and similar environments.
6931 @item distinct
6932 (the default) Always use the distinguishing font for @code{@@kbd}.
6933 @end table
6934
6935 You can embed another @@-command inside the braces of an @code{@@kbd}
6936 command. Here, for example, is the way to describe a command that
6937 would be described more verbosely as ``press the @samp{r} key and then
6938 press the @key{RETURN} key'':
6939
6940 @example
6941 @@kbd@{r @@key@{RET@}@}
6942 @end example
6943
6944 @noindent
6945 This produces: @kbd{r @key{RET}}. (The present manual uses the
6946 default for @code{@@kbdinputstyle}.)
6947
6948 You also use the @code{@@kbd} command if you are spelling out the letters
6949 you type; for example:
6950
6951 @example
6952 To give the @@code@{logout@} command,
6953 type the characters @@kbd@{l o g o u t @@key@{RET@}@}.
6954 @end example
6955
6956 @noindent
6957 This produces:
6958
6959 @quotation
6960 To give the @code{logout} command,
6961 type the characters @kbd{l o g o u t @key{RET}}.
6962 @end quotation
6963
6964 (Also, this example shows that you can add spaces for clarity. If you
6965 explicitly want to mention a space character as one of the characters of
6966 input, write @kbd{@@key@{SPC@}} for it.)@refill
6967
6968
6969 @node key
6970 @subsection @code{@@key}@{@var{key-name}@}
6971 @findex key
6972
6973 Use the @code{@@key} command for the conventional name for a key on a
6974 keyboard, as in:@refill
6975
6976 @example
6977 @@key@{RET@}
6978 @end example
6979
6980 You can use the @code{@@key} command within the argument of an
6981 @code{@@kbd} command when the sequence of characters to be typed
6982 includes one or more keys that are described by name.@refill
6983
6984 For example, to produce @kbd{C-x @key{ESC}} and @kbd{M-@key{TAB}} you
6985 would type:
6986
6987 @example
6988 @@kbd@{C-x @@key@{ESC@}@}
6989 @@kbd@{M-@@key@{TAB@}@}
6990 @end example
6991
6992 Here is a list of the recommended names for keys:
6993 @cindex Recommended names for keys
6994 @cindex Keys, recommended names
6995 @cindex Names recommended for keys
6996 @cindex Abbreviations for keys
6997
6998 @quotation
6999 @table @t
7000 @item SPC
7001 Space
7002 @item RET
7003 Return
7004 @item LFD
7005 Linefeed (however, since most keyboards nowadays do not have a Linefeed key,
7006 it might be better to call this character @kbd{C-j})
7007 @item TAB
7008 Tab
7009 @item BS
7010 Backspace
7011 @item ESC
7012 Escape
7013 @item DELETE
7014 Delete
7015 @item SHIFT
7016 Shift
7017 @item CTRL
7018 Control
7019 @item META
7020 Meta
7021 @end table
7022 @end quotation
7023
7024 @cindex META key
7025 There are subtleties to handling words like `meta' or `ctrl' that are
7026 names of modifier keys. When mentioning a character in which the
7027 modifier key is used, such as @kbd{Meta-a}, use the @code{@@kbd} command
7028 alone; do not use the @code{@@key} command; but when you are referring
7029 to the modifier key in isolation, use the @code{@@key} command. For
7030 example, write @samp{@@kbd@{Meta-a@}} to produce @kbd{Meta-a} and
7031 @samp{@@key@{META@}} to produce @key{META}.
7032
7033 As a convention in GNU manuals, @code{@@key} should not be used in
7034 index entries.
7035
7036
7037 @node samp
7038 @subsection @code{@@samp}@{@var{text}@}
7039 @findex samp
7040
7041 Use the @code{@@samp} command to indicate text that is a literal example
7042 or `sample' of a sequence of characters in a file, string, pattern, etc.
7043 Enclose the text in braces. The argument appears within single
7044 quotation marks in both the Info file and the printed manual; in
7045 addition, it is printed in a fixed-width font.@refill
7046
7047 @example
7048 To match @@samp@{foo@} at the end of the line,
7049 use the regexp @@samp@{foo$@}.
7050 @end example
7051
7052 @noindent
7053 produces
7054
7055 @quotation
7056 To match @samp{foo} at the end of the line, use the regexp
7057 @samp{foo$}.@refill
7058 @end quotation
7059
7060 Any time you are referring to single characters, you should use
7061 @code{@@samp} unless @code{@@kbd} or @code{@@key} is more appropriate.
7062 Also, you may use @code{@@samp} for entire statements in C and for entire
7063 shell commands---in this case, @code{@@samp} often looks better than
7064 @code{@@code}. Basically, @code{@@samp} is a catchall for whatever is
7065 not covered by @code{@@code}, @code{@@kbd}, or @code{@@key}.@refill
7066
7067 Only include punctuation marks within braces if they are part of the
7068 string you are specifying. Write punctuation marks outside the braces
7069 if those punctuation marks are part of the English text that surrounds
7070 the string. In the following sentence, for example, the commas and
7071 period are outside of the braces:@refill
7072
7073 @example
7074 @group
7075 In English, the vowels are @@samp@{a@}, @@samp@{e@},
7076 @@samp@{i@}, @@samp@{o@}, @@samp@{u@}, and sometimes
7077 @@samp@{y@}.
7078 @end group
7079 @end example
7080
7081 @noindent
7082 This produces:
7083
7084 @quotation
7085 In English, the vowels are @samp{a}, @samp{e},
7086 @samp{i}, @samp{o}, @samp{u}, and sometimes
7087 @samp{y}.
7088 @end quotation
7089
7090
7091 @node verb
7092 @subsection @code{@@verb}@{<char>@var{text}<char>@}
7093 @findex verb
7094 @cindex Verbatim in-line text
7095
7096 @cindex Delimiter character, for verbatim
7097 Use the @code{@@verb} command to print a verbatim sequence of
7098 characters.
7099
7100 Like @LaTeX{}'s @code{\verb} command, the verbatim text can be quoted using
7101 any unique delimiter character. Enclose the verbatim text, including the
7102 delimiters, in braces. Text is printed in a fixed-width font:
7103
7104 @example
7105 How many @@verb@{|@@|@}-escapes does one need to print this
7106 @@verb@{.@@a @@b @@c.@} string or @@verb@{+@@'e@?`@!`@{@}\+@} this?
7107 @end example
7108
7109 @noindent
7110 produces
7111
7112 @example
7113 How many @verb{|@|}-escapes does one need to print this
7114 @verb{.@a @b @c.} string or these @verb{+@'e?`{}!`\+} this?
7115 @end example
7116
7117 This is in contrast to @code{@@samp} (see the previous section),
7118 @code{@@code}, and similar commands; in those cases, the argument is
7119 normal Texinfo text, where the three characters @code{@@@{@}} are
7120 special. With @code{@@verb}, nothing is special except the delimiter
7121 character you choose.
7122
7123 It is not reliable to use @code{@@verb} inside other Texinfo
7124 constructs. In particular, it does not work to use @code{@@verb} in
7125 anything related to cross-referencing, such as section titles or
7126 figure captions.
7127
7128
7129 @node var
7130 @subsection @code{@@var}@{@var{metasyntactic-variable}@}
7131 @findex var
7132
7133 Use the @code{@@var} command to indicate metasyntactic variables. A
7134 @dfn{metasyntactic variable} is something that stands for another piece of
7135 text. For example, you should use a metasyntactic variable in the
7136 documentation of a function to describe the arguments that are passed
7137 to that function.@refill
7138
7139 Do not use @code{@@var} for the names of particular variables in
7140 programming languages. These are specific names from a program, so
7141 @code{@@code} is correct for them (@pxref{code}). For example, the
7142 XEmacs Lisp variable @code{texinfo-tex-command} is not a metasyntactic
7143 variable; it is properly formatted using @code{@@code}.
7144
7145 Do not use @code{@@var} for environment variables either; @code{@@env}
7146 is correct for them (see the next section).
7147
7148 The effect of @code{@@var} in the Info file is to change the case of the
7149 argument to all upper case. In the printed manual and HTML output, the
7150 argument is printed in slanted type.
7151
7152 @need 700
7153 For example,
7154
7155 @example
7156 To delete file @@var@{filename@},
7157 type @@samp@{rm @@var@{filename@}@}.
7158 @end example
7159
7160 @noindent
7161 produces
7162
7163 @quotation
7164 To delete file @var{filename}, type @samp{rm @var{filename}}.
7165 @end quotation
7166
7167 @noindent
7168 (Note that @code{@@var} may appear inside @code{@@code},
7169 @code{@@samp}, @code{@@file}, etc.)@refill
7170
7171 Write a metasyntactic variable all in lower case without spaces, and
7172 use hyphens to make it more readable. Thus, the Texinfo source for
7173 the illustration of how to begin a Texinfo manual looks like
7174 this:@refill
7175
7176 @example
7177 @group
7178 \input texinfo
7179 @@@@setfilename @@var@{info-file-name@}
7180 @@@@settitle @@var@{name-of-manual@}
7181 @end group
7182 @end example
7183
7184 @noindent
7185 This produces:
7186
7187 @example
7188 @group
7189 \input texinfo
7190 @@setfilename @var{info-file-name}
7191 @@settitle @var{name-of-manual}
7192 @end group
7193 @end example
7194
7195 In some documentation styles, metasyntactic variables are shown with
7196 angle brackets, for example:@refill
7197
7198 @example
7199 @dots{}, type rm <filename>
7200 @end example
7201
7202 @noindent
7203 However, that is not the style that Texinfo uses. (You can, of
7204 course, modify the sources to @file{texinfo.tex} and the Info formatting commands
7205 to output the @code{<@dots{}>} format if you wish.)@refill
7206
7207
7208 @node env
7209 @subsection @code{@@env}@{@var{environment-variable}@}
7210 @findex env
7211
7212 Use the @code{@@env} command to indicate environment variables, as used
7213 by many operating systems, including GNU. Do not use it for
7214 metasyntactic variables; use @code{@@var} instead (see the previous
7215 section).
7216
7217 @code{@@env} is equivalent to @code{@@code} in its effects.
7218 For example:
7219
7220 @example
7221 The @@env@{PATH@} environment variable @dots{}
7222 @end example
7223 @noindent produces
7224 @quotation
7225 The @env{PATH} environment variable @dots{}
7226 @end quotation
7227
7228
7229 @node file
7230 @subsection @code{@@file}@{@var{file-name}@}
7231 @findex file
7232
7233 Use the @code{@@file} command to indicate text that is the name of a
7234 file, buffer, or directory, or is the name of a node in Info. You can
7235 also use the command for file name suffixes. Do not use @code{@@file}
7236 for symbols in a programming language; use @code{@@code}.
7237
7238 Currently, @code{@@file} is equivalent to @code{@@samp} in its effects.
7239 For example,@refill
7240
7241 @example
7242 The @@file@{.el@} files are in
7243 the @@file@{/usr/local/xemacs/lisp@} directory.
7244 @end example
7245
7246 @noindent
7247 produces
7248
7249 @quotation
7250 The @file{.el} files are in
7251 the @file{/usr/local/xemacs/lisp} directory.
7252 @end quotation
7253
7254
7255 @node command
7256 @subsection @code{@@command}@{@var{command-name}@}
7257 @findex command
7258 @cindex Command names, indicating
7259 @cindex Program names, indicating
7260
7261 Use the @code{@@commannd} command to indicate command names, such as
7262 @command{ls} or @command{cc}.
7263
7264 @code{@@command} is equivalent to @code{@@code} in its effects.
7265 For example:
7266
7267 @example
7268 The command @@command@{ls@} lists directory contents.
7269 @end example
7270 @noindent produces
7271 @quotation
7272 The command @command{ls} lists directory contents.
7273 @end quotation
7274
7275 You should write the name of a program in the ordinary text font, rather
7276 than using @code{@@command}, if you regard it as a new English word,
7277 such as `XEmacs' or `Bison'.
7278
7279 When writing an entire shell command invocation, as in @samp{ls -l},
7280 you should use either @code{@@samp} or @code{@@code} at your discretion.
7281
7282
7283 @node option
7284 @subsection @code{@@option}@{@var{option-name}@}
7285 @findex option
7286
7287 Use the @code{@@option} command to indicate a command-line option; for
7288 example, @option{-l} or @option{--version} or
7289 @option{--output=@var{filename}}.
7290
7291 @code{@@option} is equivalent to @code{@@samp} in its effects.
7292 For example:
7293
7294 @example
7295 The option @@option@{-l@} produces a long listing.
7296 @end example
7297 @noindent produces
7298 @quotation
7299 The option @option{-l} produces a long listing.
7300 @end quotation
7301
7302 In tables, putting options inside @code{@@code} produces a
7303 more pleasing effect.
7304
7305 @node dfn
7306 @comment node-name, next, previous, up
7307 @subsection @code{@@dfn}@{@var{term}@}
7308 @findex dfn
7309
7310 Use the @code{@@dfn} command to identify the introductory or defining
7311 use of a technical term. Use the command only in passages whose
7312 purpose is to introduce a term which will be used again or which the
7313 reader ought to know. Mere passing mention of a term for the first
7314 time does not deserve @code{@@dfn}. The command generates italics in
7315 the printed manual, and double quotation marks in the Info file. For
7316 example:@refill
7317
7318 @example
7319 Getting rid of a file is called @@dfn@{deleting@} it.
7320 @end example
7321
7322 @noindent
7323 produces
7324
7325 @quotation
7326 Getting rid of a file is called @dfn{deleting} it.
7327 @end quotation
7328
7329 As a general rule, a sentence containing the defining occurrence of a
7330 term should be a definition of the term. The sentence does not need
7331 to say explicitly that it is a definition, but it should contain the
7332 information of a definition---it should make the meaning clear.
7333
7334 @ignore
7335 @c node ctrl, , cite, Indicating
7336 @comment node-name, next, previous, up
7337 @c subsection @code{@@ctrl}@{@var{ctrl-char}@}
7338 @findex ctrl
7339
7340 The @code{@@ctrl} command is seldom used. It describes an ASCII
7341 control character by inserting the actual character into the Info
7342 file.
7343
7344 Usually, in Texinfo, you talk what you type as keyboard entry by
7345 describing it with @code{@@kbd}: thus, @samp{@@kbd@{C-a@}} for
7346 @kbd{C-a}. Use @code{@@kbd} in this way when talking about a control
7347 character that is typed on the keyboard by the user. When talking
7348 about a control character appearing in a file or a string, do not use
7349 @code{@@kbd} since the control character is not typed. Also, do not
7350 use @samp{C-} but spell out @code{control-}, as in @samp{control-a},
7351 to make it easier for a reader to understand.@refill
7352
7353 @code{@@ctrl} is an idea from the beginnings of Texinfo which may not
7354 really fit in to the scheme of things. But there may be times when
7355 you want to use the command. The pattern is
7356 @code{@@ctrl@{@var{ch}@}}, where @var{ch} is an ASCII character
7357 whose control-equivalent is wanted. For example, to specify
7358 @samp{control-f}, you would enter@refill
7359
7360 @example
7361 @@ctrl@{f@}
7362 @end example
7363
7364 @noindent
7365 produces
7366
7367 @quotation
7368 @ctrl{f}
7369 @end quotation
7370
7371 In the Info file, this generates the specified control character, output
7372 literally into the file. This is done so a user can copy the specified
7373 control character (along with whatever else he or she wants) into another
7374 XEmacs buffer and use it. Since the `control-h',`control-i', and
7375 `control-j' characters are formatting characters, they should not be
7376 indicated with @code{@@ctrl}.@refill
7377
7378 In a printed manual, @code{@@ctrl} generates text to describe or
7379 identify that control character: an uparrow followed by the character
7380 @var{ch}.@refill
7381 @end ignore
7382
7383
7384 @node abbr
7385 @subsection @code{@@abbr}@{@var{abbreviation}[, @var{meaning}]@}
7386 @findex abbr
7387
7388 @cindex Abbreviations, tagging
7389 You can use the @code{@@abbr} command for general abbreviations. The
7390 abbreviation is given as the single argument in braces, as in
7391 @samp{@@abbr@{Comput.@}}. As a matter of style, or for particular
7392 abbreviations, you may prefer to omit periods, as in
7393 @samp{@@abbr@{Mr@} Stallman}.
7394
7395 @code{@@abbr} accepts an optional second argument, intended to be used
7396 for the meaning of the abbreviation.
7397
7398 If the abbreviation ends with a lowercase letter and a period, and is
7399 not at the end of a sentence, and has no second argument, remember to
7400 use the @code{@@.} command (@pxref{Not Ending a
7401 Sentence}) to get the correct spacing. However, you do not have to
7402 use @code{@@.} within the abbreviation itself; Texinfo automatically
7403 assumes periods within the abbreviation do not end a sentence.
7404
7405 @cindex <abbr> and <abbrev> tags
7406 In @TeX{} and in the Info output, the first argument is printed as-is;
7407 if the second argument is present, it is printed in parentheses after
7408 the abbreviation. In HTML and XML, the @code{<abbr>} tag is
7409 used; in Docbook, the @code{<abbrev>} tag is used. For instance:
7410
7411 @example
7412 @@abbr@{Comput. J., Computer Journal@}
7413 @end example
7414
7415 @noindent produces:
7416
7417 @display
7418 @abbr{Comput. J., Computer Journal}
7419 @end display
7420
7421 For abbreviations consisting of all capital letters, you may prefer to
7422 use the @code{@@acronym} command instead. See the next section for
7423 more on the usage of these two commands.
7424
7425
7426 @node acronym
7427 @subsection @code{@@acronym}@{@var{acronym}[, @var{meaning}]@}
7428 @findex acronym
7429
7430 @cindex NASA, as acronym
7431 @cindex Acronyms, tagging
7432 Use the @code{@@acronym} command for abbreviations written in all
7433 capital letters, such as `@acronym{NASA}'. The abbreviation is given as
7434 the single argument in braces, as in @samp{@@acronym@{NASA@}}. As
7435 a matter of style, or for particular acronyms, you may prefer to
7436 use periods, as in @samp{@@acronym@{N.A.S.A.@}}.
7437
7438 @code{@@acronym} accepts an optional second argument, intended to be
7439 used for the meaning of the acronym.
7440
7441 If the acronym is at the end of a sentence, and if there is no second
7442 argument, remember to use the @code{@@.} or similar command
7443 (@pxref{Ending a Sentence}) to get the correct spacing.
7444
7445 @cindex <acronym> tag
7446 In @TeX{}, the acronym is printed in slightly smaller font. In the
7447 Info output, the argument is printed as-is. In either format, if the
7448 second argument is present, it is printed in parentheses after the
7449 acronym. In HTML, Docbook, and XML, the @code{<acronym>} tag is
7450 used.
7451
7452 For instance (since GNU is a recursive acronym, we use
7453 @code{@@acronym} recursively):
7454
7455 @example
7456 @@acronym@{GNU, @@acronym@{GNU@}'s Not Unix@}
7457 @end example
7458
7459 @noindent produces:
7460
7461 @display
7462 @acronym{GNU, @acronym{GNU}'s Not Unix}
7463 @end display
7464
7465 @cindex Family names, in all capitals
7466 In some circumstances, it is conventional to print family names in all
7467 capitals. Don't use @code{@@acronym} for this, since a name is not an
7468 acronym. Use @code{@@sc} instead (@pxref{Smallcaps}).
7469
7470 @code{@@abbr} and @code{@@acronym} are closely related commands: they
7471 both signal to the reader that a shortened form is being used, and
7472 possibly give a meaning. When choosing whether to use these two
7473 commands, please bear the following in mind.
7474
7475 @itemize @minus
7476 @item
7477 In standard English usage, acronyms are a subset of abbreviations:
7478 they include pronounceable words like `@acronym{NATO}', `radar', and
7479 `snafu', and some sources also include syllable acronyms like
7480 `Usenet', hybrids like `@acronym{SIGGRAPH}', and unpronounceable
7481 initialisms like `@acronym{FBI}'.
7482
7483 @item
7484 In Texinfo, an acronym (but not an abbreviation) should consist only
7485 of capital letters and periods, no lowercase.
7486
7487 @item
7488 In @TeX{}, an acronym (but not an abbreviation) is printed in a
7489 slightly smaller font.
7490
7491 @item
7492 Some browsers place a dotted bottom border under abbreviations but not
7493 acronyms.
7494
7495 @item
7496 It's not essential to use either of these commands for all
7497 abbreviations; use your judgment. Text is perfectly readable without
7498 them.
7499
7500 @end itemize
7501
7502
7503 @node indicateurl
7504 @subsection @code{@@indicateurl}@{@var{uniform-resource-locator}@}
7505 @findex indicateurl
7506 @cindex Uniform resource locator, indicating
7507 @cindex URL, indicating
7508
7509 Use the @code{@@indicateurl} command to indicate a uniform resource
7510 locator on the World Wide Web. This is analogous to @code{@@file},
7511 @code{@@var}, etc., and is purely for markup purposes. It does not
7512 produce a link you can follow in HTML output (use the @code{@@uref}
7513 command for that, @pxref{uref,, @code{@@uref}}). It is useful for
7514 url's which do not actually exist. For example:
7515
7516 @example
7517 For example, the url might be @@indicateurl@{http://example.org/path@}.
7518 @end example
7519
7520 @noindent which produces:
7521
7522 @display
7523 For example, the url might be @indicateurl{http://example.org/path}.
7524 @end display
7525
7526
7527 @node email
7528 @subsection @code{@@email}@{@var{email-address}[, @var{displayed-text}]@}
7529 @findex email
7530
7531 Use the @code{@@email} command to indicate an electronic mail address.
7532 It takes one mandatory argument, the address, and one optional argument, the
7533 text to display (the default is the address itself).
7534
7535 @cindex Mailto link
7536 In Info, the address is shown in angle brackets, preceded by the text
7537 to display if any. In @TeX{}, the angle brackets are omitted. In
7538 HTML output, @code{@@email} produces a @samp{mailto} link that usually
7539 brings up a mail composition window. For example:
7540
7541 @example
7542 Send bug reports to @@email@{bug-texinfo@@@@gnu.org@},
7543 suggestions to the @@email@{bug-texinfo@@@@gnu.org, same place@}.
7544 @end example
7545 @noindent produces
7546 @display
7547 Send bug reports to @email{bug-texinfo@@gnu.org},
7548 suggestions to the @email{bug-texinfo@@gnu.org, same place}.
7549 @end display
7550
7551
7552 @node Emphasis
7553 @section Emphasizing Text
7554 @cindex Emphasizing text
7555
7556 Usually, Texinfo changes the font to mark words in the text according to
7557 what category the words belong to; an example is the @code{@@code} command.
7558 Most often, this is the best way to mark words.
7559 However, sometimes you will want to emphasize text without indicating a
7560 category. Texinfo has two commands to do this. Also, Texinfo has
7561 several commands that specify the font in which @TeX{} will typeset
7562 text. These commands have no effect on Info and only one of them,
7563 the @code{@@r} command, has any regular use.@refill
7564
7565 @menu
7566 * emph & strong:: How to emphasize text in Texinfo.
7567 * Smallcaps:: How to use the small caps font.
7568 * Fonts:: Various font commands for printed output.
7569 @end menu
7570
7571 @node emph & strong
7572 @subsection @code{@@emph}@{@var{text}@} and @code{@@strong}@{@var{text}@}
7573 @cindex Emphasizing text, font for
7574 @findex emph
7575 @findex strong
7576
7577 The @code{@@emph} and @code{@@strong} commands are for emphasis;
7578 @code{@@strong} is stronger. In printed output, @code{@@emph} produces
7579 @emph{italics} and @code{@@strong} produces @strong{bold}.
7580
7581 For example,
7582
7583 @example
7584 @group
7585 @@strong@{Caution:@} @@samp@{rm * .[^.]*@}
7586 removes @@emph@{all@} files in the directory.
7587 @end group
7588 @end example
7589
7590 @noindent
7591 produces the following in printed output and HTML:
7592
7593 @quotation
7594 @strong{Caution}: @samp{rm * .[^.]*}
7595 removes @emph{all} files in the directory.
7596 @end quotation
7597
7598 @noindent
7599 and the following in Info:
7600
7601 @example
7602 *Caution:* `rm * .[^.]*' removes _all_
7603 files in the directory.
7604 @end example
7605
7606 The @code{@@strong} command is seldom used except to mark what is, in
7607 effect, a typographical element, such as the word `Caution' in the
7608 preceding example.
7609
7610 In the Info output, @code{@@emph} surrounds the text with underscores
7611 (@samp{_}), and @code{@@strong} puts asterisks around the text.
7612
7613 @quotation Caution
7614 Do not use @code{@@strong} with the word @samp{Note}; Info will
7615 mistake the combination for a cross reference. (It's usually
7616 redundant, anyway.) Use a phrase such as @strong{Please notice} or
7617 @strong{Caution} instead, or the optional argument to
7618 @code{@@quotation}---@samp{Note} is allowable there.
7619 @end quotation
7620
7621
7622 @node Smallcaps
7623 @subsection @code{@@sc}@{@var{text}@}: The Small Caps Font
7624 @cindex Small caps font
7625 @findex sc @r{(small caps font)}
7626
7627 Use the @samp{@@sc} command to set text in @sc{a small caps font}
7628 (where possible). Write the text you want to be in small caps between
7629 braces in lower case, like this:
7630
7631 @example
7632 Richard @@sc@{Stallman@} founded @@acronym@{GNU@}.
7633 @end example
7634
7635 @noindent
7636 This produces:
7637
7638 @display
7639 Richard @sc{Stallman} founded @acronym{GNU}.
7640 @end display
7641
7642 As shown here, we recommend using @code{@@acronym} for actual
7643 acronyms (@pxref{acronym}), and reserving @code{@@sc} for special
7644 cases where you want small caps. The output is not the same
7645 (@code{@@acronym} prints in a smaller text font, not the small caps
7646 font), but more importantly it describes the actual text more
7647 accurately.
7648
7649 Family names are one case where small capitals are sometimes desirable,
7650 also as shown here.
7651
7652 @cindex <small> tag
7653 @TeX{} typesets any uppercase letters between the braces of an
7654 @code{@@sc} command in full-size capitals; only lowercase letters are
7655 printed in the small caps font. In the Info output, the argument to
7656 @code{@@sc} is printed in all upper case. In HTML, the argument is
7657 uppercased and the output marked with the @code{<small>} tag to reduce
7658 the font size.
7659
7660 Since it's redundant to mark all-uppercase text with @code{@@sc},
7661 @command{makeinfo} warns about such usage.
7662
7663 We recommend using regular mixed case wherever possible.
7664
7665
7666 @node Fonts
7667 @subsection Fonts for Printing, Not Info
7668 @cindex Fonts for printing, not Info
7669
7670 @findex fonttextsize
7671 @cindex Font size, reducing
7672 @cindex Reducing font size
7673 @cindex Smaller fonts
7674 Texinfo provides one command to change the size of the main body font
7675 in the @TeX{} output for a document: @code{@@fonttextsize}. It has no
7676 effect at all in other output. It takes a single argument on the
7677 remainder of the line, which must be either @samp{10} or @samp{11}.
7678 For example:
7679
7680 @example
7681 @@fonttextsize 10
7682 @end example
7683
7684 @cindex Printing cost, reducing
7685 The effect is to reduce the body font to a 10@dmn{pt} size (the
7686 default is 11@dmn{pt}). Fonts for other elements, such as sections
7687 and chapters, are reduced accordingly. This should only be used in
7688 conjunction with @code{@@smallbook} (@pxref{smallbook,,Printing
7689 ``Small'' Books}) or similar, since 10@dmn{pt} fonts on standard paper
7690 (8.5x11 or A4) are too small. One reason to use this command is to
7691 save pages, and hence printing cost, for physical books.
7692
7693 Texinfo does not at present have commands to switch the font family
7694 to use, or more general size-changing commands.
7695
7696 @cindex Styles, font
7697 Texinfo also provides a number of font commands that specify font changes
7698 in the printed manual and (where possible) in the HTML output, but
7699 have no effect in the Info file. All the commands apply to an
7700 argument that follows, surrounded by braces.
7701
7702 @table @code
7703 @item @@b
7704 @findex b @r{(bold font)}
7705 @cindex Bold font
7706 selects @b{bold} face;
7707
7708 @item @@i
7709 @findex i @r{(italic font)}
7710 @cindex Italic font
7711 selects an @i{italic} font;
7712
7713 @item @@r
7714 @findex r @r{(roman font)}
7715 @cindex Roman font
7716 @cindex Default font
7717 selects a @r{roman} font, which is the usual font in which text is
7718 printed. It may or may not be seriffed.
7719
7720 @item @@sansserif
7721 @findex sansserif @r{(sans serif font)}
7722 @cindex Sans serif font
7723 selects a @sansserif{sans serif} font;
7724
7725 @item @@slanted
7726 @findex slanted @r{(slanted font)}
7727 @cindex Slanted font
7728 @cindex Oblique font
7729 selects a @slanted{slanted} font;
7730
7731 @item @@t
7732 @findex t @r{(typewriter font)}
7733 @cindex Monospace font
7734 @cindex Fixed-width font
7735 @cindex Typewriter font
7736 selects the @t{fixed-width}, typewriter-style font used by @code{@@code};
7737
7738 @end table
7739
7740 (The commands with longer names were invented much later than the
7741 others, at which time it did not seem desirable to use very short
7742 names for such an infrequently needed feature.)
7743
7744 @cindex <lineannotation> Docbook tag
7745 Only the @code{@@r} command has much use: in example-like
7746 environments, you can use the @code{@@r} command to write comments in
7747 the standard roman font instead of the fixed-width font. This looks
7748 better in printed output, and produces a @code{<lineannotation>} tag
7749 in Docbook output.
7750
7751 For example,
7752
7753 @example
7754 @group
7755 @@lisp
7756 (+ 2 2) ; @@r@{Add two plus two.@}
7757 @@end lisp
7758 @end group
7759 @end example
7760
7761 @noindent
7762 produces
7763
7764 @lisp
7765 (+ 2 2) ; @r{Add two plus two.}
7766 @end lisp
7767
7768 In general, you should avoid using the other font commands. Some of
7769 them are only useful when documenting functionality of specific font
7770 effects, such as in @TeX{} and related packages.
7771
7772
7773 @node Quotations and Examples
7774 @chapter Quotations and Examples
7775
7776 Quotations and examples are blocks of text consisting of one or more
7777 whole paragraphs that are set off from the bulk of the text and
7778 treated differently. They are usually indented in the output.
7779
7780 @findex end
7781 In Texinfo, you always begin a quotation or example by writing an
7782 @@-command at the beginning of a line by itself, and end it by writing
7783 an @code{@@end} command that is also at the beginning of a line by
7784 itself. For instance, you begin an example by writing @code{@@example}
7785 by itself at the beginning of a line and end the example by writing
7786 @code{@@end example} on a line by itself, at the beginning of that
7787 line, and with only one space between the @code{@@end} and the
7788 @code{example}.
7789
7790 @menu
7791 * Block Enclosing Commands:: Different constructs for different purposes.
7792 * quotation:: Writing a quotation.
7793 * example:: Writing an example in a fixed-width font.
7794 * verbatim:: Writing a verbatim example.
7795 * verbatiminclude:: Including a file verbatim.
7796 * lisp:: Illustrating Lisp code.
7797 * small:: Examples in a smaller font.
7798 * display:: Writing an example in the current font.
7799 * format:: Writing an example without narrowed margins.
7800 * exdent:: Undo indentation on a line.
7801 * flushleft & flushright:: Pushing text flush left or flush right.
7802 * noindent:: Preventing paragraph indentation.
7803 * indent:: Forcing paragraph indentation.
7804 * cartouche:: Drawing rounded rectangles around examples.
7805 @end menu
7806
7807
7808 @node Block Enclosing Commands
7809 @section Block Enclosing Commands
7810
7811 Here are commands for quotations and examples, explained further in the
7812 following sections:
7813
7814 @table @code
7815 @item @@quotation
7816 Indicate text that is quoted. The text is filled, indented (from both
7817 margins), and printed in a roman font by default.
7818
7819 @item @@example
7820 Illustrate code, commands, and the like. The text is printed
7821 in a fixed-width font, and indented but not filled.
7822
7823 @item @@verbatim
7824 Mark a piece of text that is to be printed verbatim; no character
7825 substitutions are made and all commands are ignored, until the next
7826 @code{@@end verbatim}. The text is printed in a fixed-width font,
7827 and not indented or filled. Extra spaces and blank lines are
7828 significant, and tabs are expanded.
7829
7830 @item @@smallexample
7831 Same as @code{@@example}, except that in @TeX{} this command typesets
7832 text in a smaller font.
7833
7834 @item @@lisp
7835 Like @code{@@example}, but specifically for illustrating Lisp code. The
7836 text is printed in a fixed-width font, and indented but not filled.
7837
7838 @item @@smalllisp
7839 Is to @code{@@lisp} as @code{@@smallexample} is to @code{@@example}.
7840
7841 @item @@display
7842 Display illustrative text. The text is indented but not filled, and
7843 no font is selected (so, by default, the font is roman).@refill
7844
7845 @item @@smalldisplay
7846 Is to @code{@@display} as @code{@@smallexample} is to @code{@@example}.
7847
7848 @item @@format
7849 Like @code{@@display} (the text is not filled and no font is selected),
7850 but the text is not indented.
7851
7852 @item @@smallformat
7853 Is to @code{@@format} as @code{@@smallexample} is to @code{@@example}.
7854 @end table
7855
7856 The @code{@@exdent} command is used within the above constructs to
7857 undo the indentation of a line.
7858
7859 The @code{@@flushleft} and @code{@@flushright} commands are used to line
7860 up the left or right margins of unfilled text.@refill
7861
7862 The @code{@@noindent} command may be used after one of the above
7863 constructs to prevent the following text from being indented as a new
7864 paragraph.
7865
7866 You can use the @code{@@cartouche} environment around one of the above
7867 constructs to highlight the example or quotation by drawing a box with
7868 rounded corners around it. @xref{cartouche, , Drawing Cartouches Around
7869 Examples}.
7870
7871
7872 @node quotation
7873 @section @code{@@quotation}: Block quotations
7874 @cindex Quotations
7875 @findex quotation
7876
7877 The text of a quotation is processed normally (regular font, text is
7878 filled) except that:
7879
7880 @itemize @bullet
7881 @item
7882 the margins are closer to the center of the page, so the whole of the
7883 quotation is indented;
7884
7885 @item
7886 and the first lines of paragraphs are indented no more than other lines.
7887
7888 @end itemize
7889
7890 @quotation
7891 This is an example of text written between an @code{@@quotation}
7892 command and an @code{@@end quotation} command. An @code{@@quotation}
7893 command is most often used to indicate text that is excerpted from
7894 another (real or hypothetical) printed work.
7895 @end quotation
7896
7897 Write an @code{@@quotation} command as text on a line by itself. This
7898 line will disappear from the output. Mark the end of the quotation
7899 with a line beginning with and containing only @code{@@end quotation}.
7900 The @code{@@end quotation} line will likewise disappear from the
7901 output.
7902
7903 @code{@@quotation} takes one optional argument, given on the remainder
7904 of the line. This text, if present, is included at the beginning of
7905 the quotation in bold or otherwise emphasized, and followed with a
7906 @samp{:}. For example:
7907
7908 @example
7909 @@quotation Note
7910 This is
7911 a foo.
7912 @@end quotation
7913 @end example
7914
7915 @noindent
7916 produces
7917
7918 @quotation Note
7919 This is
7920 a foo.
7921 @end quotation
7922
7923 If the @code{@@quotation} argument is exactly one of these words:
7924
7925 @example
7926 Caution Important Note Tip Warning
7927 @end example
7928
7929 @cindex <note> Docbook tag
7930 @cindex <blockquote> HTML tag
7931 @noindent then the Docbook output uses corresponding special tags
7932 (@code{<note>}, etc.) instead of the default @code{<blockquote>}.
7933 HTML output always uses @code{<blockquote>}.
7934
7935
7936 @node example
7937 @section @code{@@example}: Example Text
7938 @cindex Examples, formatting them
7939 @cindex Formatting examples
7940 @findex example
7941
7942 The @code{@@example} environment is used to indicate an example that
7943 is not part of the running text, such as computer input or output.
7944 Write an @code{@@example} command at the beginning of a line by
7945 itself. Mark the end of the example with an @code{@@end example}
7946 command, also written at the beginning of a line by itself.
7947
7948 An @code{@@example} environment has the following characteristics:
7949
7950 @itemize
7951 @item Each line in the input file is a line in the output; that is,
7952 the source text is not filled as it normally is.
7953 @item Extra spaces and blank lines are significant.
7954 @item The output is indented.
7955 @item The output uses a fixed-width font.
7956 @item Texinfo commands @emph{are} expanded; if you want the output to
7957 be the input verbatim, use the @code{@@verbatim} environment instead
7958 (@pxref{verbatim,,@code{@@verbatim}}).
7959 @end itemize
7960
7961 For example,
7962
7963 @example
7964 @@example
7965 cp foo @@var@{dest1@}; \
7966 cp foo @@var@{dest2@}
7967 @@end example
7968 @end example
7969
7970 @noindent
7971 produces
7972
7973 @example
7974 cp foo @var{dest1}; \
7975 cp foo @var{dest2}
7976 @end example
7977
7978 The lines containing @code{@@example} and @code{@@end example} will
7979 disappear from the output. To make the output look good, you should
7980 put a blank line before the @code{@@example} and another blank line
7981 after the @code{@@end example}. Blank lines inside the beginning
7982 @code{@@example} and the ending @code{@@end example}, on the other
7983 hand, do appear in the output.
7984
7985 @quotation Caution
7986 Do not use tabs in the lines of an example! (Or anywhere else in
7987 Texinfo, except in verbatim environments.) @TeX{} treats tabs as
7988 single spaces, and that is not what they look like. In XEmacs, you can
7989 use @kbd{M-x untabify} to convert tabs in a region to multiple spaces.
7990 @end quotation
7991
7992 Examples are often, logically speaking, ``in the middle'' of a
7993 paragraph, and the text that continues afterwards should not be
7994 indented, as in the example above. The @code{@@noindent} command
7995 prevents a piece of text from being indented as if it were a new
7996 paragraph (@pxref{noindent,,@code{@@noindent}}.
7997
7998 If you want to embed code fragments within sentences, instead of
7999 displaying them, use the @code{@@code} command or its relatives
8000 (@pxref{code,,@code{@@code}}).
8001
8002 If you wish to write a ``comment'' on a line of an example in the
8003 normal roman font, you can use the @code{@@r} command (@pxref{Fonts}).
8004
8005
8006 @node verbatim
8007 @section @code{@@verbatim}: Literal Text
8008 @findex verbatim
8009 @cindex Verbatim environment
8010
8011 Use the @code{@@verbatim} environment for printing of text that may
8012 contain special characters or commands that should not be interpreted,
8013 such as computer input or output (@code{@@example} interprets its text
8014 as regular Texinfo commands). This is especially useful for including automatically
8015 generated files in a Texinfo manual.
8016
8017 In general, the output will be just the same as the input. No
8018 character substitutions are made, e.g., all spaces and blank lines are
8019 significant, including tabs. In the printed manual, the text is
8020 typeset in a fixed-width font, and not indented or filled.
8021
8022 Write a @code{@@verbatim} command at the beginning of a line by itself.
8023 This line will disappear from the output. Mark the end of the verbatim
8024 block with a @code{@@end verbatim} command, also written at the
8025 beginning of a line by itself. The @code{@@end verbatim} will also
8026 disappear from the output.
8027
8028 For example:
8029 @c oops, got to trick this a bit: can't use @end verbatim inside @verbatim
8030
8031 @example
8032 @exdent @t{@@verbatim}
8033 @exdent @t{@{}
8034 @exdent @key{TAB}@t{@@command with strange characters: @@'e}
8035 @exdent @t{expand@key{TAB}me}
8036 @exdent @t{@}}
8037 @exdent @t{@@end verbatim}
8038 @end example
8039
8040 @noindent
8041 This produces:
8042
8043 @verbatim
8044 {
8045 @command with strange characters: @'e
8046 expand me
8047 }
8048 @end verbatim
8049
8050 Since the lines containing @code{@@verbatim} and @code{@@end verbatim}
8051 produce no output, typically you should put a blank line before the
8052 @code{@@verbatim} and another blank line after the @code{@@end
8053 verbatim}. Blank lines between the beginning @code{@@verbatim} and
8054 the ending @code{@@end verbatim} will appear in the output.
8055
8056 @cindex Verbatim, small
8057 @cindex Small verbatim
8058 You can get a ``small'' verbatim by enclosing the @code{@@verbatim} in
8059 an @code{@@smallformat} environment, as shown here:
8060
8061 @c more cheating ...
8062 @smallexample
8063 @exdent @t{@@smallformat}
8064 @exdent @t{@@verbatim}
8065 @exdent @t{... still verbatim, but in a smaller font ...}
8066 @exdent @t{@@end verbatim}
8067 @exdent @t{@@end smallformat}
8068 @end smallexample
8069
8070 Finally, a word of warning: it is not reliable to use
8071 @code{@@verbatim} inside other Texinfo constructs.
8072
8073
8074 @node verbatiminclude
8075 @section @code{@@verbatiminclude} @var{file}: Include a File Verbatim
8076 @cindex Verbatim, include file
8077 @cindex Including a file verbatim
8078 @findex verbatiminclude
8079
8080 You can include the exact contents of a file in the document with the
8081 @code{@@verbatiminclude} command:
8082
8083 @example
8084 @@verbatiminclude @var{filename}
8085 @end example
8086
8087 The contents of @var{filename} is printed in a verbatim environment
8088 (@pxref{verbatim,,@code{@@verbatim}}). Generally, the file is printed
8089 exactly as it is, with all special characters and white space
8090 retained. No indentation is added; if you want indentation, enclose
8091 the @code{@@verbatiminclude} within @code{@@example}
8092 (@pxref{example,,@code{@@example}}).
8093
8094 The name of the file is taken literally, with a single exception:
8095 @code{@@value@{@var{var}@}} references are expanded. This makes it
8096 possible to include files in other directories within a distribution,
8097 for instance:
8098
8099 @example
8100 @@verbatiminclude @@value@{top_srcdir@}/NEWS
8101 @end example
8102
8103 @noindent (You still have to get @code{top_srcdir} defined in the
8104 first place.)
8105
8106 For a method on printing the file contents in a smaller font size, see
8107 the end of the previous section on @code{@@verbatim}.
8108
8109
8110 @node lisp
8111 @section @code{@@lisp}: Marking a Lisp Example
8112 @findex lisp
8113 @cindex Lisp example
8114
8115 The @code{@@lisp} command is used for Lisp code. It is synonymous
8116 with the @code{@@example} command.
8117
8118 @lisp
8119 This is an example of text written between an
8120 @code{@@lisp} command and an @code{@@end lisp} command.
8121 @end lisp
8122
8123 Use @code{@@lisp} instead of @code{@@example} to preserve information
8124 regarding the nature of the example. This is useful, for example, if
8125 you write a function that evaluates only and all the Lisp code in a
8126 Texinfo file. Then you can use the Texinfo file as a Lisp
8127 library.@footnote{It would be straightforward to extend Texinfo to work
8128 in a similar fashion for C, Fortran, or other languages.}
8129
8130 Mark the end of @code{@@lisp} with @code{@@end lisp} on a line by
8131 itself.
8132
8133
8134 @node small
8135 @section @code{@@small@dots{}} Block Commands
8136 @cindex Small examples
8137 @cindex Examples in smaller fonts
8138 @cindex Lisp examples in smaller fonts
8139 @findex smalldisplay
8140 @findex smallexample
8141 @findex smallformat
8142 @findex smalllisp
8143
8144 In addition to the regular @code{@@example} and @code{@@lisp} commands,
8145 Texinfo has ``small'' example-style commands. These are
8146 @code{@@smalldisplay}, @code{@@smallexample}, @code{@@smallformat}, and
8147 @code{@@smalllisp}.
8148
8149 In Info, the @code{@@small@dots{}} commands are equivalent to their
8150 non-small companion commands.
8151
8152 In @TeX{}, however, the @code{@@small@dots{}} commands typeset text in
8153 a smaller font than the non-small example commands. Consequently,
8154 many examples containing long lines fit on a page without needing to
8155 be shortened.
8156
8157 Mark the end of an @code{@@small@dots{}} block with a corresponding
8158 @code{@@end small@dots{}}. For example, pair @code{@@smallexample} with
8159 @code{@@end smallexample}.
8160
8161 Here is an example of the font used by the @code{@@small@dots{}}
8162 commands (in Info, the output will be the same as usual):
8163
8164 @smallexample
8165 @dots{} to make sure that you have the freedom to
8166 distribute copies of free software (and charge for
8167 this service if you wish), that you receive source
8168 code or can get it if you want it, that you can
8169 change the software or use pieces of it in new free
8170 programs; and that you know you can do these things.
8171 @end smallexample
8172
8173 The @code{@@small@dots{}} commands make it easier to prepare manuals
8174 without forcing you to edit examples by hand to fit them onto narrower
8175 pages.
8176
8177 As a general rule, a printed document looks much better if you use
8178 only one of (for instance) @code{@@example} or @code{@@smallexample}
8179 consistently within a chapter.
8180
8181
8182 @node display
8183 @section @code{@@display} and @code{@@smalldisplay}
8184 @cindex Display formatting
8185 @findex display
8186
8187 The @code{@@display} command begins a kind of example, where each line
8188 of input produces a line of output, and the output is indented. It is
8189 thus like the @code{@@example} command except that, in a printed
8190 manual, @code{@@display} does not select the fixed-width font. In
8191 fact, it does not specify the font at all, so that the text appears in
8192 the same font it would have appeared in without the @code{@@display}
8193 command.
8194
8195 @display
8196 This is an example of text written between an @code{@@display} command
8197 and an @code{@@end display} command. The @code{@@display} command
8198 indents the text, but does not fill it.
8199 @end display
8200
8201 @findex smalldisplay
8202 Texinfo also provides a command @code{@@smalldisplay}, which is like
8203 @code{@@display} but uses a smaller font in @code{@@smallbook} format.
8204 @xref{small}.
8205
8206 The @code{@@table} command (@pxref{table}) does not work inside
8207 @code{@@display}. Since @code{@@display} is line-oriented, it doesn't
8208 make sense to use them together. If you want to indent a table, try
8209 @code{@@quotation} (@pxref{quotation}).
8210
8211
8212 @node format
8213 @section @code{@@format} and @code{@@smallformat}
8214 @findex format
8215
8216 The @code{@@format} command is similar to @code{@@example} except
8217 that, in the printed manual, @code{@@format} does not select the
8218 fixed-width font and does not narrow the margins.
8219
8220 @format
8221 This is an example of text written between an @code{@@format} command
8222 and an @code{@@end format} command. As you can see
8223 from this example,
8224 the @code{@@format} command does not fill the text.
8225 @end format
8226
8227 @findex smallformat
8228 Texinfo also provides a command @code{@@smallformat}, which is like
8229 @code{@@format} but uses a smaller font in @code{@@smallbook} format.
8230 @xref{small}.
8231
8232
8233
8234 @node exdent
8235 @section @code{@@exdent}: Undoing a Line's Indentation
8236 @cindex Indentation undoing
8237 @findex exdent
8238
8239 The @code{@@exdent} command removes any indentation a line might have.
8240 The command is written at the beginning of a line and applies only to
8241 the text that follows the command that is on the same line. Do not use
8242 braces around the text. In a printed manual, the text on an
8243 @code{@@exdent} line is printed in the roman font.@refill
8244
8245 @code{@@exdent} is usually used within examples. Thus,@refill
8246
8247 @example
8248 @group
8249 @@example
8250 This line follows an @@@@example command.
8251 @@exdent This line is exdented.
8252 This line follows the exdented line.
8253 The @@@@end example comes on the next line.
8254 @@end example
8255 @end group
8256 @end example
8257
8258 @noindent
8259 produces
8260
8261 @example
8262 @group
8263 This line follows an @@example command.
8264 @exdent This line is exdented.
8265 This line follows the exdented line.
8266 The @@end example comes on the next line.
8267 @end group
8268 @end example
8269
8270 In practice, the @code{@@exdent} command is rarely used.
8271 Usually, you un-indent text by ending the example and
8272 returning the page to its normal width.@refill
8273
8274
8275 @node flushleft & flushright
8276 @section @code{@@flushleft} and @code{@@flushright}
8277 @findex flushleft
8278 @findex flushright
8279 @cindex Ragged right
8280 @cindex Ragged left
8281
8282 The @code{@@flushleft} and @code{@@flushright} commands line up the
8283 ends of lines on the left and right margins of a page,
8284 but do not fill the text. The commands are written on lines of their
8285 own, without braces. The @code{@@flushleft} and @code{@@flushright}
8286 commands are ended by @code{@@end flushleft} and @code{@@end
8287 flushright} commands on lines of their own.@refill
8288
8289 @need 1500
8290 For example,
8291
8292 @example
8293 @group
8294 @@flushleft
8295 This text is
8296 written flushleft.
8297 @@end flushleft
8298 @end group
8299 @end example
8300
8301 @noindent
8302 produces
8303
8304 @quotation
8305 @flushleft
8306 This text is
8307 written flushleft.
8308 @end flushleft
8309 @end quotation
8310
8311
8312 @code{@@flushright} produces the type of indentation often used in the
8313 return address of letters. For example,
8314
8315 @example
8316 @group
8317 @@flushright
8318 Here is an example of text written
8319 flushright. The @@code@{@@flushright@} command
8320 right justifies every line but leaves the
8321 left end ragged.
8322 @@end flushright
8323 @end group
8324 @end example
8325
8326 @noindent
8327 produces
8328
8329 @flushright
8330 Here is an example of text written
8331 flushright. The @code{@@flushright} command
8332 right justifies every line but leaves the
8333 left end ragged.
8334 @end flushright
8335
8336
8337 @node noindent
8338 @section @code{@@noindent}: Omitting Indentation
8339 @cindex Omitting indentation
8340 @cindex Suppressing indentation
8341 @cindex Indentation, omitting
8342 @findex noindent
8343
8344 An example or other inclusion can break a paragraph into segments.
8345 Ordinarily, the formatters indent text that follows an example as a new
8346 paragraph. You can prevent this on a case-by-case basis by writing
8347 @code{@@noindent} at the beginning of a line, preceding the continuation
8348 text. You can also disable indentation for all paragraphs globally with
8349 @code{@@paragraphindent} (@pxref{paragraphindent, Paragraph Indenting}).
8350
8351 It is best to write @code{@@noindent} on a line by itself, since in most
8352 environments, spaces following the command will not be ignored. It's ok
8353 to use it at the beginning of a line, with text following, outside of
8354 any environment.
8355
8356 @need 1500
8357 For example:
8358
8359 @example
8360 @group
8361 @@example
8362 This is an example
8363 @@end example
8364
8365 @@noindent
8366 This line is not indented. As you can see, the
8367 beginning of the line is fully flush left with the line
8368 that follows after it. (This whole example is between
8369 @@code@{@@@@display@} and @@code@{@@@@end display@}.)
8370 @end group
8371 @end example
8372
8373 @noindent produces:
8374
8375 @display
8376
8377 @example
8378 This is an example
8379 @end example
8380
8381 @noindent
8382 This line is not indented. As you can see, the
8383 beginning of the line is fully flush left with the line
8384 that follows after it. (This whole example is between
8385 @code{@@display} and @code{@@end display}.)
8386
8387 @end display
8388
8389 To adjust the number of blank lines properly in the Info file output,
8390 remember that the line containing @code{@@noindent} does not generate a
8391 blank line, and neither does the @code{@@end example} line.
8392
8393 In the Texinfo source file for this manual, each line that says
8394 `produces' is preceded by @code{@@noindent}.
8395
8396 Do not put braces after an @code{@@noindent} command; they are not
8397 necessary, since @code{@@noindent} is a command used outside of
8398 paragraphs (@pxref{Command Syntax}).
8399
8400
8401 @node indent
8402 @section @code{@@indent}: Forcing Indentation
8403 @cindex Forcing indentation
8404 @cindex Inserting indentation
8405 @cindex Indentation, forcing
8406 @findex indent
8407
8408 @indent
8409 To complement the @code{@@noindent} command (see the previous
8410 section), Texinfo provides the @code{@@indent} command that forces a
8411 paragraph to be indented. This paragraph, for instance, is indented
8412 using an @code{@@indent} command. The first paragraph of a section is
8413 the most likely place to use @code{@@indent}, to override the normal
8414 behavior of no indentation there (@pxref{paragraphindent}).
8415
8416 It is best to write @code{@@indent} on a line by itself, since in most
8417 environments, spaces following the command will not be ignored. The
8418 @code{@@indent} line will not generate a blank line in the Info output
8419 within an environment.
8420
8421 However, it is ok to use it at the beginning of a line, with text
8422 following, outside of any environment.
8423
8424 Do not put braces after an @code{@@indent} command; they are not
8425 necessary, since @code{@@indent} is a command used outside of
8426 paragraphs (@pxref{Command Syntax}).
8427
8428
8429 @node cartouche
8430 @section @code{@@cartouche}: Rounded Rectangles Around Examples
8431 @findex cartouche
8432 @cindex Box with rounded corners
8433 @cindex Rounded rectangles, around examples
8434
8435 In a printed manual, the @code{@@cartouche} command draws a box with
8436 rounded corners around its contents. In HTML, a normal rectangle is
8437 drawn (that's the best HTML can do). @code{@@cartouche} has no effect
8438 in Info output.
8439
8440 You can use this command to further highlight an example or quotation.
8441 For instance, you could write a manual in which one type of example is
8442 surrounded by a cartouche for emphasis.
8443
8444 For example,
8445
8446 @example
8447 @@cartouche
8448 @@example
8449 % pwd
8450 /usr/local/share/xemacs
8451 @@end example
8452 @@end cartouche
8453 @end example
8454
8455 @noindent
8456 surrounds the two-line example with a box with rounded corners, in the
8457 printed manual.
8458
8459 The output from the example looks like this (if you're reading this in
8460 Info, you'll see the @code{@@cartouche} had no effect):
8461
8462 @cartouche
8463 @example
8464 % pwd
8465 /usr/local/info
8466 @end example
8467 @end cartouche
8468
8469 For proper output in HTML, it's necessary to put the
8470 @code{@@cartouche} around the @code{@@example}, and not the other way
8471 around. This limitation of @command{makeinfo} may be removed one day.
8472
8473 @code{@@cartouche} also implies @code{@@group} (@pxref{group}).
8474
8475 @node Lists and Tables
8476 @chapter Lists and Tables
8477 @cindex Making lists and tables
8478 @cindex Lists and tables, making
8479 @cindex Tables and lists, making
8480
8481 Texinfo has several ways of making lists and tables. Lists can be
8482 bulleted or numbered; two-column tables can highlight the items in
8483 the first column; multi-column tables are also supported.
8484
8485 @menu
8486 * Introducing Lists:: Texinfo formats lists for you.
8487 * itemize:: How to construct a simple list.
8488 * enumerate:: How to construct a numbered list.
8489 * Two-column Tables:: How to construct a two-column table.
8490 * Multi-column Tables:: How to construct generalized tables.
8491 @end menu
8492
8493 @node Introducing Lists
8494 @section Introducing Lists
8495
8496 Texinfo automatically indents the text in lists or tables, and numbers
8497 an enumerated list. This last feature is useful if you modify the
8498 list, since you do not need to renumber it yourself.@refill
8499
8500 Numbered lists and tables begin with the appropriate @@-command at the
8501 beginning of a line, and end with the corresponding @code{@@end}
8502 command on a line by itself. The table and itemized-list commands
8503 also require that you write formatting information on the same line as
8504 the beginning @@-command.@refill
8505
8506 Begin an enumerated list, for example, with an @code{@@enumerate}
8507 command and end the list with an @code{@@end enumerate} command.
8508 Begin an itemized list with an @code{@@itemize} command, followed on
8509 the same line by a formatting command such as @code{@@bullet}, and end
8510 the list with an @code{@@end itemize} command.@refill
8511 @findex end
8512
8513 Precede each element of a list with an @code{@@item} or @code{@@itemx}
8514 command.@refill
8515
8516 @sp 1
8517 @noindent
8518 Here is an itemized list of the different kinds of table and lists:@refill
8519
8520 @itemize @bullet
8521 @item
8522 Itemized lists with and without bullets.
8523
8524 @item
8525 Enumerated lists, using numbers or letters.
8526
8527 @item
8528 Two-column tables with highlighting.
8529 @end itemize
8530
8531 @sp 1
8532 @noindent
8533 Here is an enumerated list with the same items:@refill
8534
8535 @enumerate
8536 @item
8537 Itemized lists with and without bullets.
8538
8539 @item
8540 Enumerated lists, using numbers or letters.
8541
8542 @item
8543 Two-column tables with highlighting.
8544 @end enumerate
8545
8546 @sp 1
8547 @noindent
8548 And here is a two-column table with the same items and their
8549 @w{@@-commands}:@refill
8550
8551 @table @code
8552 @item @@itemize
8553 Itemized lists with and without bullets.
8554
8555 @item @@enumerate
8556 Enumerated lists, using numbers or letters.
8557
8558 @item @@table
8559 @itemx @@ftable
8560 @itemx @@vtable
8561 Two-column tables, optionally with indexing.
8562 @end table
8563
8564
8565 @node itemize
8566 @section @code{@@itemize}: Making an Itemized List
8567 @cindex Itemization
8568 @findex itemize
8569
8570 The @code{@@itemize} command produces sequences of indented
8571 paragraphs, with a bullet or other mark inside the left margin
8572 at the beginning of each paragraph for which such a mark is desired.@refill
8573
8574 @cindex @code{@@w}, for blank items
8575 Begin an itemized list by writing @code{@@itemize} at the beginning of
8576 a line. Follow the command, on the same line, with a character or a
8577 Texinfo command that generates a mark. Usually, you will write
8578 @code{@@bullet} after @code{@@itemize}, but you can use
8579 @code{@@minus}, or any command or character that results in a single
8580 character in the Info file. If you don't want any mark at all, use
8581 @code{@@w}. (When you write the mark command such as
8582 @code{@@bullet} after an @code{@@itemize} command, you may omit the
8583 @samp{@{@}}.) If you don't specify a mark command, the default is
8584 @code{@@bullet}.
8585
8586 Write the text of the indented paragraphs themselves after the
8587 @code{@@itemize}, up to another line that says @code{@@end
8588 itemize}.@refill
8589
8590 @findex item
8591 At the beginning of each paragraph for which a mark in the margin is
8592 desired, write a line that starts with @code{@@item}. It is ok to
8593 have text following the @code{@@item}.
8594
8595 Usually, you should put a blank line before an @code{@@item}. This
8596 puts a blank line in the Info file. (@TeX{} inserts the proper
8597 interline whitespace in either case.) Except when the entries are
8598 very brief, these blank lines make the list look better.@refill
8599
8600 Here is an example of the use of @code{@@itemize}, followed by the
8601 output it produces. @code{@@bullet} produces an @samp{*} in Info and a
8602 round dot in @TeX{}.
8603
8604 @example
8605 @group
8606 @@itemize @@bullet
8607 @@item
8608 Some text for foo.
8609
8610 @@item
8611 Some text
8612 for bar.
8613 @@end itemize
8614 @end group
8615 @end example
8616
8617 @noindent
8618 This produces:
8619
8620 @quotation
8621 @itemize @bullet
8622 @item
8623 Some text for foo.
8624
8625 @item
8626 Some text
8627 for bar.
8628 @end itemize
8629 @end quotation
8630
8631 Itemized lists may be embedded within other itemized lists. Here is a
8632 list marked with dashes embedded in a list marked with bullets:@refill
8633
8634 @example
8635 @group
8636 @@itemize @@bullet
8637 @@item
8638 First item.
8639
8640 @@itemize @@minus
8641 @@item
8642 Inner item.
8643
8644 @@item
8645 Second inner item.
8646 @@end itemize
8647
8648 @@item
8649 Second outer item.
8650 @@end itemize
8651 @end group
8652 @end example
8653
8654 @noindent
8655 This produces:
8656
8657 @quotation
8658 @itemize @bullet
8659 @item
8660 First item.
8661
8662 @itemize @minus
8663 @item
8664 Inner item.
8665
8666 @item
8667 Second inner item.
8668 @end itemize
8669
8670 @item
8671 Second outer item.
8672 @end itemize
8673 @end quotation
8674
8675
8676 @node enumerate
8677 @section @code{@@enumerate}: Making a Numbered or Lettered List
8678 @cindex Enumeration
8679 @findex enumerate
8680
8681 @code{@@enumerate} is like @code{@@itemize} (@pxref{itemize,,
8682 @code{@@itemize}}), except that the labels on the items are
8683 successive integers or letters instead of bullets.
8684
8685 Write the @code{@@enumerate} command at the beginning of a line. The
8686 command does not require an argument, but accepts either a number or a
8687 letter as an option. Without an argument, @code{@@enumerate} starts the
8688 list with the number @samp{1}. With a numeric argument, such as
8689 @samp{3}, the command starts the list with that number. With an upper
8690 or lower case letter, such as @samp{a} or @samp{A}, the command starts
8691 the list with that letter.
8692
8693 Write the text of the enumerated list in the same way as an itemized
8694 list: write a line starting with @code{@@item} at the beginning of
8695 each paragraph that you want enumerated. It is ok to have text
8696 following the @code{@@item}.
8697
8698 You should put a blank line between entries in the list.
8699 This generally makes it easier to read the Info file.
8700
8701 @need 1500
8702 Here is an example of @code{@@enumerate} without an argument:
8703
8704 @example
8705 @group
8706 @@enumerate
8707 @@item
8708 Underlying causes.
8709
8710 @@item
8711 Proximate causes.
8712 @@end enumerate
8713 @end group
8714 @end example
8715
8716 @noindent
8717 This produces:
8718
8719 @enumerate
8720 @item
8721 Underlying causes.
8722
8723 @item
8724 Proximate causes.
8725 @end enumerate
8726 @sp 1
8727 Here is an example with an argument of @kbd{3}:@refill
8728 @sp 1
8729 @example
8730 @group
8731 @@enumerate 3
8732 @@item
8733 Predisposing causes.
8734
8735 @@item
8736 Precipitating causes.
8737
8738 @@item
8739 Perpetuating causes.
8740 @@end enumerate
8741 @end group
8742 @end example
8743
8744 @noindent
8745 This produces:
8746
8747 @enumerate 3
8748 @item
8749 Predisposing causes.
8750
8751 @item
8752 Precipitating causes.
8753
8754 @item
8755 Perpetuating causes.
8756 @end enumerate
8757 @sp 1
8758 Here is a brief summary of the alternatives. The summary is constructed
8759 using @code{@@enumerate} with an argument of @kbd{a}.@refill
8760 @sp 1
8761 @enumerate a
8762 @item
8763 @code{@@enumerate}
8764
8765 Without an argument, produce a numbered list, starting with the number
8766 1.@refill
8767
8768 @item
8769 @code{@@enumerate @var{positive-integer}}
8770
8771 With a (positive) numeric argument, start a numbered list with that
8772 number. You can use this to continue a list that you interrupted with
8773 other text.@refill
8774
8775 @item
8776 @code{@@enumerate @var{upper-case-letter}}
8777
8778 With an upper case letter as argument, start a list
8779 in which each item is marked
8780 by a letter, beginning with that upper case letter.@refill
8781
8782 @item
8783 @code{@@enumerate @var{lower-case-letter}}
8784
8785 With a lower case letter as argument, start a list
8786 in which each item is marked by
8787 a letter, beginning with that lower case letter.@refill
8788 @end enumerate
8789
8790 You can also nest enumerated lists, as in an outline.@refill
8791
8792 @node Two-column Tables
8793 @section Making a Two-column Table
8794 @cindex Tables, making two-column
8795 @findex table
8796
8797 @code{@@table} is similar to @code{@@itemize} (@pxref{itemize,,
8798 @code{@@itemize}}), but allows you to specify a name or heading line for
8799 each item. The @code{@@table} command is used to produce two-column
8800 tables, and is especially useful for glossaries, explanatory
8801 exhibits, and command-line option summaries.
8802
8803 @menu
8804 * table:: How to construct a two-column table.
8805 * ftable vtable:: Automatic indexing for two-column tables.
8806 * itemx:: How to put more entries in the first column.
8807 @end menu
8808
8809 @node table
8810 @subsection Using the @code{@@table} Command
8811
8812 @cindex Definition lists, typesetting
8813 Use the @code{@@table} command to produce two-column tables. It is
8814 usually listed for ``definition lists'' of various sorts, where you
8815 have a list of terms and a brief text with each one.
8816
8817 Write the @code{@@table} command at the beginning of a line, after a
8818 blank line, and follow it on the same line with an argument that is a
8819 Texinfo ``indicating'' command such as @code{@@code}, @code{@@samp},
8820 @code{@@var}, @code{@@option}, or @code{@@kbd} (@pxref{Indicating}).
8821
8822 This command will be applied to the text that goes into the first
8823 column of each item and thus determines how it will be highlighted.
8824 For example, @code{@@table @@code} will cause the text in the first
8825 column to be output as if it @code{@@code} command.
8826
8827 @findex asis
8828 You may also use the @code{@@asis} command as an argument to
8829 @code{@@table}. @code{@@asis} is a command that does nothing; if you
8830 use this command after @code{@@table}, the first column entries are
8831 output without added highlighting (``as is'').
8832
8833 The @code{@@table} command works with other commands besides those
8834 explicitly mentioned here. However, you can only use commands that
8835 normally take arguments in braces. (In this case, however, you use
8836 the command name without an argument, because the subsequent
8837 @code{@@item}'s will supply the argument.)
8838
8839 @findex item
8840 Begin each table entry with an @code{@@item} command at the beginning
8841 of a line. Write the first column text on the same line as the
8842 @code{@@item} command. Write the second column text on the line
8843 following the @code{@@item} line and on subsequent lines. (You do not
8844 need to type anything for an empty second column entry.) You may
8845 write as many lines of supporting text as you wish, even several
8846 paragraphs. But only the text on the same line as the @code{@@item}
8847 will be placed in the first column (including any footnotes).
8848
8849 Normally, you should put a blank line before an @code{@@item} line.
8850 This puts a blank line in the Info file. Except when the entries are
8851 very brief, a blank line looks better.
8852
8853 End the table with a line consisting of @code{@@end table}, followed
8854 by a blank line. @TeX{} will always start a new paragraph after the
8855 table, so the blank line is needed for the Info output to be analogous.
8856
8857 @need 1500
8858 The following table, for example, highlights the text in the first
8859 column with an @code{@@samp} command:
8860
8861 @example
8862 @group
8863 @@table @@samp
8864 @@item foo
8865 This is the text for
8866 @@samp@{foo@}.
8867
8868 @@item bar
8869 Text for @@samp@{bar@}.
8870 @@end table
8871 @end group
8872 @end example
8873
8874 @noindent
8875 This produces:
8876
8877 @table @samp
8878 @item foo
8879 This is the text for
8880 @samp{foo}.
8881 @item bar
8882 Text for @samp{bar}.
8883 @end table
8884
8885 If you want to list two or more named items with a single block of
8886 text, use the @code{@@itemx} command. (@xref{itemx,,@code{@@itemx}}.)
8887
8888
8889 @node ftable vtable
8890 @subsection @code{@@ftable} and @code{@@vtable}
8891 @cindex Tables with indexes
8892 @cindex Indexing table entries automatically
8893 @findex ftable
8894 @findex vtable
8895
8896 The @code{@@ftable} and @code{@@vtable} commands are the same as the
8897 @code{@@table} command except that @code{@@ftable} automatically enters
8898 each of the items in the first column of the table into the index of
8899 functions and @code{@@vtable} automatically enters each of the items in
8900 the first column of the table into the index of variables. This
8901 simplifies the task of creating indices. Only the items on the same
8902 line as the @code{@@item} commands are indexed, and they are indexed in
8903 exactly the form that they appear on that line. @xref{Indices},
8904 for more information about indices.@refill
8905
8906 Begin a two-column table using @code{@@ftable} or @code{@@vtable} by
8907 writing the @@-command at the beginning of a line, followed on the same
8908 line by an argument that is a Texinfo command such as @code{@@code},
8909 exactly as you would for an @code{@@table} command; and end the table
8910 with an @code{@@end ftable} or @code{@@end vtable} command on a line by
8911 itself.
8912
8913 See the example for @code{@@table} in the previous section.
8914
8915 @node itemx
8916 @subsection @code{@@itemx}
8917 @cindex Two named items for @code{@@table}
8918 @findex itemx
8919
8920 Use the @code{@@itemx} command inside a table when you have two or more
8921 first column entries for the same item, each of which should appear on a
8922 line of its own.
8923
8924 Use @code{@@item} for the first entry, and @code{@@itemx} for all
8925 subsequent entries; @code{@@itemx} must always follow an @code{@@item}
8926 command, with no blank line intervening.
8927
8928 The @code{@@itemx} command works exactly like @code{@@item} except
8929 that it does not generate extra vertical space above the first column
8930 text. If you have multiple consecutive @code{@@itemx} commands, do
8931 not insert any blank lines between them.
8932
8933 For example,
8934
8935 @example
8936 @group
8937 @@table @@code
8938 @@item upcase
8939 @@itemx downcase
8940 These two functions accept a character or a string as
8941 argument, and return the corresponding upper case (lower
8942 case) character or string.
8943 @@end table
8944 @end group
8945 @end example
8946
8947 @noindent
8948 This produces:
8949
8950 @table @code
8951 @item upcase
8952 @itemx downcase
8953 These two functions accept a character or a string as
8954 argument, and return the corresponding upper case (lower
8955 case) character or string.@refill
8956 @end table
8957
8958 @noindent
8959 (Note also that this example illustrates multi-line supporting text in
8960 a two-column table.)@refill
8961
8962
8963 @node Multi-column Tables
8964 @section @code{@@multitable}: Multi-column Tables
8965 @cindex Tables, making multi-column
8966 @findex multitable
8967
8968 @code{@@multitable} allows you to construct tables with any number of
8969 columns, with each column having any width you like.
8970
8971 You define the column widths on the @code{@@multitable} line itself, and
8972 write each row of the actual table following an @code{@@item} command,
8973 with columns separated by an @code{@@tab} command. Finally, @code{@@end
8974 multitable} completes the table. Details in the sections below.
8975
8976 @menu
8977 * Multitable Column Widths:: Defining multitable column widths.
8978 * Multitable Rows:: Defining multitable rows, with examples.
8979 @end menu
8980
8981 @node Multitable Column Widths
8982 @subsection Multitable Column Widths
8983 @cindex Multitable column widths
8984 @cindex Column widths, defining for multitables
8985 @cindex Widths, defining multitable column
8986
8987 You can define the column widths for a multitable in two ways: as
8988 fractions of the line length; or with a prototype row. Mixing the two
8989 methods is not supported. In either case, the widths are defined
8990 entirely on the same line as the @code{@@multitable} command.
8991
8992 @enumerate
8993 @item
8994 @findex columnfractions
8995 @cindex Line length, column widths as fraction of
8996 To specify column widths as fractions of the line length, write
8997 @code{@@columnfractions} and the decimal numbers (presumably less than
8998 1; a leading zero is allowed and ignored) after the
8999 @code{@@multitable} command, as in:
9000
9001 @example
9002 @@multitable @@columnfractions .33 .33 .33
9003 @end example
9004
9005 The fractions need not add up exactly to 1.0, as these do not. This
9006 allows you to produce tables that do not need the full line length.
9007
9008 @item
9009 @cindex Prototype row, column widths defined by
9010 To specify a prototype row, write the longest entry for each column
9011 enclosed in braces after the @code{@@multitable} command. For example:
9012
9013 @example
9014 @@multitable @{some text for column one@} @{for column two@}
9015 @end example
9016
9017 @noindent
9018 The first column will then have the width of the typeset `some text for
9019 column one', and the second column the width of `for column two'.
9020
9021 The prototype entries need not appear in the table itself.
9022
9023 Although we used simple text in this example, the prototype entries can
9024 contain Texinfo commands; markup commands such as @code{@@code} are
9025 particularly likely to be useful.
9026
9027 @end enumerate
9028
9029
9030 @node Multitable Rows
9031 @subsection Multitable Rows
9032 @cindex Multitable rows
9033 @cindex Rows, of a multitable
9034
9035 @findex item
9036 @findex tab
9037 After the @code{@@multitable} command defining the column widths (see
9038 the previous section), you begin each row in the body of a multitable
9039 with @code{@@item}, and separate the column entries with @code{@@tab}.
9040 Line breaks are not special within the table body, and you may break
9041 input lines in your source file as necessary.
9042
9043 @findex headitem
9044 @cindex Heading row, in table
9045 @cindex <thead> HTML tag
9046 You can also use @code{@@headitem} instead of @code{@@item} to produce
9047 a @dfn{heading row}. The @TeX{} output for such a row is in bold, and
9048 the HTML, XML, and Docbook output uses the @code{<thead>} tag. In
9049 Info, the heading row is followed by a separator line made of dashes
9050 (@samp{-} characters).
9051
9052 Here is a complete example of a multi-column table (the text is from
9053 @cite{The XEmacs Users' Manual}, @pxref{Split Window,, Splitting Windows,
9054 xemacs, XEmacs User's Manual}):
9055
9056 @example
9057 @@multitable @@columnfractions .15 .45 .4
9058 @@headitem Key @@tab Command @@tab Description
9059 @@item C-x 2
9060 @@tab @@code@{split-window-vertically@}
9061 @@tab Split the selected window into two windows,
9062 with one above the other.
9063 @@item C-x 3
9064 @@tab @@code@{split-window-horizontally@}
9065 @@tab Split the selected window into two windows
9066 positioned side by side.
9067 @@item C-Mouse-2
9068 @@tab
9069 @@tab In the mode line or scroll bar of a window,
9070 split that window.
9071 @@end multitable
9072 @end example
9073
9074 @noindent
9075 produces:
9076
9077 @multitable @columnfractions .15 .45 .4
9078 @headitem Key @tab Command @tab Description
9079 @item C-x 2
9080 @tab @code{split-window-vertically}
9081 @tab Split the selected window into two windows,
9082 with one above the other.
9083 @item C-x 3
9084 @tab @code{split-window-horizontally}
9085 @tab Split the selected window into two windows
9086 positioned side by side.
9087 @item C-Mouse-2
9088 @tab
9089 @tab In the mode line or scroll bar of a window,
9090 split that window.
9091 @end multitable
9092
9093
9094 @node Special Displays
9095 @chapter Special Displays
9096 @cindex Special displays
9097
9098 The commands in this chapter allow you to write text that is specially
9099 displayed (output format permitting), outside of the normal document
9100 flow.
9101
9102 One set of such commands is for creating ``floats'', that is, figures,
9103 tables, and the like, set off from the main text, possibly numbered,
9104 captioned, and/or referred to from elsewhere in the document. Images
9105 are often included in these displays.
9106
9107 Another group of commands is for creating footnotes in Texinfo.
9108
9109 @menu
9110 * Floats:: Figures, tables, and the like.
9111 * Images:: Including graphics and images.
9112 * Footnotes:: Writing footnotes.
9113 @end menu
9114
9115
9116 @node Floats
9117 @section Floats
9118 @cindex Floats, in general
9119
9120 A @dfn{float} is a display which is set off from the main text. It is
9121 typically labelled as being a ``Figure'', ``Table'', ``Example'', or
9122 some similar type.
9123
9124 @cindex Floating, not yet implemented
9125 A float is so-named because, in principle, it can be moved to the
9126 bottom or top of the current page, or to a following page, in the
9127 printed output. (Floating does not make sense in other output
9128 formats.) In the present version of Texinfo, however, this floating
9129 is unfortunately not yet implemented. Instead, the floating material
9130 is simply output at the current location, more or less as if it were
9131 an @code{@@group} (@pxref{group,,@code{@@group}}).
9132
9133 @menu
9134 * float:: Producing floating material.
9135 * caption shortcaption:: Specifying descriptions for floats.
9136 * listoffloats:: A table of contents for floats.
9137 @end menu
9138
9139
9140 @node float
9141 @subsection @code{@@float} [@var{type}][,@var{label}]: Floating Material
9142 @findex float
9143 @cindex Float environment
9144
9145 To produce floating material, enclose the material you want to be
9146 displayed separate between @code{@@float} and @code{@@end float}
9147 commands, on lines by themselves.
9148
9149 Floating material uses @code{@@image} to display an already-existing
9150 graphic (@pxref{Images}), or @code{@@multitable} to display a table
9151 (@pxref{Multi-column Tables}). However, the contents of the float can
9152 be anything. Here's an example with simple text:
9153
9154 @example
9155 @@float Figure,fig:ex1
9156 This is an example float.
9157 @@end float
9158 @end example
9159
9160 @noindent And the output:
9161
9162 @float Figure,fig:ex1
9163 This is an example float.
9164 @end float
9165
9166 As shown in the example, @code{@@float} takes two arguments (separated
9167 by a comma), @var{type} and @var{label}. Both are optional.
9168
9169 @table @var
9170 @item type
9171 Specifies the sort of float this is; typically a word such as
9172 ``Figure'', ``Table'', etc. If not given, and @var{label} is, any
9173 cross-referencing will simply use a bare number.
9174
9175 @item label
9176 Specifies a cross-reference label for this float. If given, this
9177 float is automatically given a number, and will appear in any
9178 @code{@@listoffloats} output (@pxref{listoffloats}). Cross-references
9179 to @var{label} are allowed.
9180
9181 @cindex Floats, making unnumbered
9182 @cindex Unnumbered float, creating
9183 On the other hand, if @var{label} is not given, then the float will
9184 not be numbered and consequently will not appear in the
9185 @code{@@listoffloats} output or be cross-referenceable.
9186 @end table
9187
9188 @noindent Normally, you specify both @var{type} and @var{label}, to get a
9189 labeled and numbered float.
9190
9191 @cindex Floats, numbering of
9192 @cindex Numbering of floats
9193 In Texinfo, all floats are numbered the same way: with the chapter
9194 number (or appendix letter), a period, and the float number, which
9195 simply counts 1, 2, 3, @dots{}, and is reset at each chapter. Each
9196 float type is counted independently.
9197
9198 Floats within an @code{@@unnumbered} are numbered, or outside of any
9199 chapter, are simply numbered consecutively from 1.
9200
9201 These numbering conventions are not, at present, changeable.
9202
9203
9204 @node caption shortcaption
9205 @subsection @code{@@caption} & @code{@@shortcaption}
9206 @findex caption
9207 @findex shortcaption
9208 @cindex Captions, for floats
9209 @cindex Short captions, for lists of floats
9210
9211 You may write an @code{@@caption} anywhere within a @code{@@float}
9212 environment, to define a caption for the float. It is not allowed in
9213 any other context. @code{@@caption} takes a single argument, enclosed
9214 in braces. Here's an example:
9215
9216 @example
9217 @@float
9218 An example float, with caption.
9219 @@caption@{Caption for example float.@}
9220 @@end float
9221 @end example
9222
9223 @noindent The output is:
9224
9225 @float
9226 An example float, with caption.
9227 @caption{Caption for example float.}
9228 @end float
9229
9230 @code{@@caption} can appear anywhere within the float; it is not
9231 processed until the @code{@@end float}. The caption text is usually a
9232 sentence or two, but may consist of several paragraphs if necessary.
9233
9234 In the output, the caption always appears below the float; this is not
9235 currently changeable. It is preceded by the float type and/or number,
9236 as specified to the @code{@@float} command (see the previous section).
9237
9238 The @code{@@shortcaption} command likewise may be used only within
9239 @code{@@float}, and takes a single argument in braces. The short
9240 caption text is used instead of the caption text in a list of floats
9241 (see the next section). Thus, you can write a long caption for the
9242 main document, and a short title to appear in the list of floats. For
9243 example:
9244
9245 @example
9246 @@float
9247 ... as above ...
9248 @@shortcaption@{Text for list of floats.@}
9249 @@end float
9250 @end example
9251
9252 The text for @code{@@caption} and @code{@@shortcaption} may not
9253 contain comments (@code{@@c}), verbatim text (@code{@@verb}),
9254 environments such as @code{@@example}, or other complex constructs.
9255
9256
9257 @node listoffloats
9258 @subsection @code{@@listoffloats}: Tables of Contents for Floats
9259 @findex listoffloats
9260 @cindex List of floats
9261 @cindex Floats, list of
9262 @cindex Table of contents, for floats
9263
9264 You can write a @code{@@listoffloats} command to generate a list of
9265 floats for a given float type (@pxref{float}), analogous to the
9266 document's overall table of contents. Typically, it is written in its
9267 own @code{@@unnumbered} node to provide a heading and structure,
9268 rather like @code{@@printindex} (@pxref{Printing Indices & Menus}).
9269
9270 @code{@@listoffloats} takes one optional argument, the float type.
9271 Here's an example:
9272
9273 @example
9274 @@node List of Figures
9275 @@unnumbered List of Figures
9276 @@listoffloats Figure
9277 @end example
9278
9279 @noindent And the output from @code{@@listoffloats}:
9280
9281 @display
9282 @listoffloats Figure
9283 @end display
9284
9285 Without any argument, @code{@@listoffloats} generates a list of
9286 floats for which no float type was specified, i.e., no first argument
9287 to the @code{@@float} command (@pxref{float}).
9288
9289 Each line in the list of floats contains the float type (if any),
9290 the float number, and the caption, if any---the @code{@@shortcaption}
9291 argument, if it was specified, else the @code{@@caption} argument.
9292 In Info, the result is a menu where each float can be selected. In
9293 HTML, each line is a link to the float. In printed output, the page
9294 number is included.
9295
9296 Unnumbered floats (those without cross-reference labels) are omitted
9297 from the list of floats.
9298
9299
9300 @node Images
9301 @section Inserting Images
9302
9303 @cindex Images, inserting
9304 @cindex Pictures, inserting
9305 @findex image
9306
9307 You can insert an image given in an external file with the
9308 @code{@@image} command. Although images can be used anywhere,
9309 including the middle of a paragraph, we describe them in this chapter
9310 since they are most often part of a displayed figure or example.
9311
9312 @menu
9313 * Image Syntax::
9314 * Image Scaling::
9315 @end menu
9316
9317
9318 @node Image Syntax
9319 @subsection Image Syntax
9320
9321 Here is the synopsis of the @code{@@image} command:
9322
9323 @example
9324 @@image@{@var{filename}@r{[,} @var{width}@r{[,} @var{height}@r{[,} @var{alttext}@r{[, }@var{extension}@r{]]]]}@}
9325 @end example
9326
9327 @cindex Formats for images
9328 @cindex Image formats
9329 The @var{filename} argument is mandatory, and must not have an
9330 extension, because the different processors support different formats:
9331
9332 @itemize @bullet
9333 @item
9334 @pindex eps image format
9335 @TeX{} reads the file @file{@var{filename}.eps} (Encapsulated PostScript
9336 format).
9337 @item
9338 @pindex pdftex@r{, and images}
9339 @pindex png image format
9340 @pindex jpeg image format
9341 @pindex pdf image inclusions
9342 pdf@TeX{} reads @file{@var{filename}.png}, @file{@var{filename}.jpg},
9343 @file{@var{filename}.jpeg}, or @file{@var{filename}.pdf} (in that
9344 order). It also tries uppercase versions of the extensions. The PDF
9345 format cannot support EPS images, so they must be converted first.
9346 @item
9347 @code{makeinfo} includes @file{@var{filename}.txt} verbatim for
9348 Info output (more or less as if it was an @code{@@example}).
9349 @item
9350 @code{makeinfo} uses the optional fifth argument @var{extension} to
9351 @code{@@image} for the filename extension, if it is specified. For example:
9352
9353 @pindex XPM image format
9354 @example
9355 @@image@{foo,,,,.xpm@}
9356 @end example
9357
9358 @noindent
9359 will cause @code{makeinfo} to look for @file{foo.xpm} before any others.
9360
9361 @end itemize
9362
9363 The @var{width} and @var{height} arguments are described in the next
9364 section.
9365
9366 For @TeX{} output, if an image is the only thing in a paragraph it
9367 will ordinarily be displayed on a line by itself, respecting the
9368 current environment indentation, but without the normal paragraph
9369 indentation. If you want it centered, use @code{@@center}
9370 (@pxref{titlefont center sp,,@code{@@titlefont @@center @@sp}}).
9371
9372 @cindex Alt attribute for images
9373 @cindex Images, alternate text for
9374 @findex - (in image alt string)
9375 For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for
9376 inline images to the optional @var{alttext} (fourth) argument to
9377 @code{@@image}, if supplied. If not supplied, @code{makeinfo} uses
9378 the full file name of the image being displayed. The @var{alttext} is
9379 taken as Texinfo text, so special characters such as @samp{"} and
9380 @samp{<} and @samp{&} are escaped in the HTML and XML output; also,
9381 you can get an empty @code{alt} string with @code{@@-} (a command
9382 that produces no output; @pxref{- and hyphenation}).
9383
9384 For Info output, the @code{alt} string is also processed as Texinfo
9385 text and output. In this case, @samp{\} is escaped as @samp{\\} and
9386 @samp{"} as @samp{\"}; no other escapes are done.
9387
9388 @cindex PNG image format
9389 @cindex JPEG image format
9390 If you do not supply the optional @var{extension} (fifth) argument,
9391 @code{makeinfo} first tries @file{@var{filename}.png}; if that does
9392 not exist, it tries @file{@var{filename}.jpg}. If that does not exist
9393 either, it complains.
9394
9395 In Info output, @code{makeinfo} writes a reference to the binary image
9396 file (trying @var{filename} suffixed with @file{@var{extension}},
9397 @file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order)
9398 if one exists. It also literally includes the @file{.txt} file if one
9399 exists. This way, Info readers which can display images (such as the
9400 XEmacs Info browser, running under X) can do so, whereas Info readers
9401 which can only use text (such as the standalone Info reader) can
9402 display the textual version.
9403
9404 @cindex @samp{^@@^H} for images in Info
9405 The implementation of this is to put the following construct into the
9406 Info output:
9407
9408 @example
9409 ^@@^H[image src="@var{binaryfile}" text="@var{txtfile}"
9410 alt="@var{alttext} ... ^@@^H]
9411 @end example
9412
9413 @noindent where @samp{^@@} and @samp{^H} stand for the actual null and
9414 backspace control characters. If one of the files is not present, the
9415 corresponding argument is omitted.
9416
9417 The reason for mentioning this here is that older Info browsers (this
9418 feature was introduced in Texinfo version 4.6) will display the above
9419 literally, which, although not pretty, should not be harmful.
9420
9421
9422 @node Image Scaling
9423 @subsection Image Scaling
9424
9425 @cindex Images, scaling
9426 @cindex Scaling images
9427 @cindex Width of images
9428 @cindex Height of images
9429 @cindex Aspect ratio of images
9430 @cindex Distorting images
9431 The optional @var{width} and @var{height} arguments to the
9432 @code{@@image} command (see the previous section) specify the size to
9433 scale the image to. They are ignored for Info output. If neither is
9434 specified, the image is presented in its natural size (given in the
9435 file); if only one is specified, the other is scaled proportionately;
9436 and if both are specified, both are respected, thus possibly distorting
9437 the original image by changing its aspect ratio.
9438
9439 @cindex Dimensions and image sizes
9440 The @var{width} and @var{height} may be specified using any valid @TeX{}
9441 dimension, namely:
9442
9443 @table @asis
9444 @item pt
9445 @cindex Points (dimension)
9446 point (72.27pt = 1in)
9447 @item pc
9448 @cindex Picas
9449 pica (1pc = 12pt)
9450 @item bp
9451 @cindex Big points
9452 big point (72bp = 1in)
9453 @item in
9454 @cindex Inches
9455 inch
9456 @item cm
9457 @cindex Centimeters
9458 centimeter (2.54cm = 1in)
9459 @item mm
9460 @cindex Millimeters
9461 millimeter (10mm = 1cm)
9462 @item dd
9463 @cindex Did@^ot points
9464 did@^ot point (1157dd = 1238pt)
9465 @item cc
9466 @cindex Ciceros
9467 cicero (1cc = 12dd)
9468 @item sp
9469 @cindex Scaled points
9470 scaled point (65536sp = 1pt)
9471 @end table
9472
9473 @pindex ridt.eps
9474 For example, the following will scale a file @file{ridt.eps} to one
9475 inch vertically, with the width scaled proportionately:
9476
9477 @example
9478 @@image@{ridt,,1in@}
9479 @end example
9480
9481 @pindex epsf.tex
9482 For @code{@@image} to work with @TeX{}, the file @file{epsf.tex} must be
9483 installed somewhere that @TeX{} can find it. (The standard location is
9484 @file{@var{texmf}/tex/generic/dvips/epsf.tex}, where @var{texmf} is a
9485 root of your @TeX{} directory tree.) This file is included in the
9486 Texinfo distribution and is also available from
9487 @uref{ftp://tug.org/tex/epsf.tex}, among other places.
9488
9489 @code{@@image} can be used within a line as well as for displayed
9490 figures. Therefore, if you intend it to be displayed, be sure to leave
9491 a blank line before the command, or the output will run into the
9492 preceding text.
9493
9494 Image scaling is presently implemented only in @TeX{}, not in HTML or
9495 any other sort of output.
9496
9497
9498 @node Footnotes
9499 @section Footnotes
9500 @cindex Footnotes
9501 @findex footnote
9502
9503 A @dfn{footnote} is for a reference that documents or elucidates the
9504 primary text.@footnote{A footnote should complement or expand upon
9505 the primary text, but a reader should not need to read a footnote to
9506 understand the primary text. For a thorough discussion of footnotes,
9507 see @cite{The Chicago Manual of Style}, which is published by the
9508 University of Chicago Press.} Footnotes are distracting; use them
9509 sparingly, if at all. Standard bibliographical references are better
9510 placed in a bibliography at the end of a document than in footnotes
9511 throughout.
9512
9513 @menu
9514 * Footnote Commands:: How to write a footnote in Texinfo.
9515 * Footnote Styles:: Controlling how footnotes appear in Info.
9516 @end menu
9517
9518
9519 @node Footnote Commands
9520 @subsection Footnote Commands
9521
9522 In Texinfo, footnotes are created with the @code{@@footnote} command.
9523 This command is followed immediately by a left brace, then by the text
9524 of the footnote, and then by a terminating right brace. Footnotes may
9525 be of any length (they will be broken across pages if necessary), but
9526 are usually short. The template is:
9527
9528 @example
9529 ordinary text@@footnote@{@var{text of footnote}@}
9530 @end example
9531
9532 As shown here, the @code{@@footnote} command should come right after the
9533 text being footnoted, with no intervening space; otherwise, the footnote
9534 marker might end up starting a line.
9535
9536 For example, this clause is followed by a sample footnote@footnote{Here
9537 is the sample footnote.}; in the Texinfo source, it looks like
9538 this:
9539
9540 @example
9541 @dots{}a sample footnote@@footnote@{Here is the sample
9542 footnote.@}; in the Texinfo source@dots{}
9543 @end example
9544
9545 As you can see, the source includes two punctuation marks next to each
9546 other; in this case, @samp{.@};} is the sequence. This is normal (the
9547 first ends the footnote and the second belongs to the sentence being
9548 footnoted), so don't worry that it looks odd.
9549
9550 In a printed manual or book, the reference mark for a footnote is a
9551 small, superscripted number; the text of the footnote appears at the
9552 bottom of the page, below a horizontal line.
9553
9554 In Info, the reference mark for a footnote is a pair of parentheses
9555 with the footnote number between them, like this: @samp{(1)}. The
9556 reference mark is followed by a cross-reference link to the footnote's
9557 text.
9558
9559 In the HTML output, footnote references are marked with a small,
9560 superscripted number which is rendered as a hypertext link to the
9561 footnote text.
9562
9563 By the way, footnotes in the argument of an @code{@@item} command for a
9564 @code{@@table} must be on the same line as the @code{@@item}
9565 (as usual). @xref{Two-column Tables}.
9566
9567
9568 @node Footnote Styles
9569 @subsection Footnote Styles
9570
9571 Info has two footnote styles, which determine where the text of the
9572 footnote is located:
9573
9574 @itemize @bullet
9575 @cindex @samp{@r{End}} node footnote style
9576 @item
9577 In the `End' node style, all the footnotes for a single node
9578 are placed at the end of that node. The footnotes are separated from
9579 the rest of the node by a line of dashes with the word
9580 @samp{Footnotes} within it. Each footnote begins with an
9581 @samp{(@var{n})} reference mark.
9582
9583 @need 700
9584 @noindent
9585 Here is an example of a single footnote in the end of node style:@refill
9586
9587 @example
9588 @group
9589 --------- Footnotes ---------
9590
9591 (1) Here is a sample footnote.
9592 @end group
9593 @end example
9594
9595 @cindex @samp{@r{Separate}} footnote style
9596 @item
9597 In the `Separate' node style, all the footnotes for a single
9598 node are placed in an automatically constructed node of
9599 their own. In this style, a ``footnote reference'' follows
9600 each @samp{(@var{n})} reference mark in the body of the
9601 node. The footnote reference is actually a cross reference
9602 which you use to reach the footnote node.
9603
9604 The name of the node with the footnotes is constructed
9605 by appending @w{@samp{-Footnotes}} to the name of the node
9606 that contains the footnotes. (Consequently, the footnotes'
9607 node for the @file{Footnotes} node is
9608 @w{@file{Footnotes-Footnotes}}!) The footnotes' node has an
9609 `Up' node pointer that leads back to its parent node.
9610
9611 @noindent
9612 Here is how the first footnote in this manual looks after being
9613 formatted for Info in the separate node style:
9614
9615 @smallexample
9616 @group
9617 File: texinfo.info Node: Overview-Footnotes, Up: Overview
9618
9619 (1) The first syllable of "Texinfo" is pronounced like "speck", not
9620 "hex". @dots{}
9621 @end group
9622 @end smallexample
9623 @end itemize
9624
9625 Unless your document has long and important footnotes (as in, say,
9626 Gibbon's @cite{Decline and Fall @dots{}}), we recommend the @samp{end}
9627 style, as it is simpler for readers to follow.
9628
9629 @findex footnotestyle
9630 Use the @code{@@footnotestyle} command to specify an Info file's
9631 footnote style. Write this command at the beginning of a line followed
9632 by an argument, either @samp{end} for the end node style or
9633 @samp{separate} for the separate node style.
9634
9635 @need 700
9636 For example,
9637
9638 @example
9639 @@footnotestyle end
9640 @end example
9641 @noindent
9642 or
9643 @example
9644 @@footnotestyle separate
9645 @end example
9646
9647 Write an @code{@@footnotestyle} command before or shortly after the
9648 end-of-header line at the beginning of a Texinfo file. (If you
9649 include the @code{@@footnotestyle} command between the start-of-header
9650 and end-of-header lines, the region formatting commands will format
9651 footnotes as specified.)@refill
9652
9653 If you do not specify a footnote style, the formatting commands use
9654 their default style. Currently, @code{texinfo-format-buffer} and
9655 @code{texinfo-format-region} use the `separate' style and
9656 @code{makeinfo} uses the `end' style.
9657
9658
9659 @node Indices
9660 @chapter Indices
9661 @cindex Indices
9662
9663 Using Texinfo, you can generate indices without having to sort and
9664 collate entries manually. In an index, the entries are listed in
9665 alphabetical order, together with information on how to find the
9666 discussion of each entry. In a printed manual, this information
9667 consists of page numbers. In an Info file, this information is a menu
9668 entry leading to the first node referenced.
9669
9670 Texinfo provides several predefined kinds of index: an index
9671 for functions, an index for variables, an index for concepts, and so
9672 on. You can combine indices or use them for other than their
9673 canonical purpose. Lastly, you can define your own new indices.
9674
9675 @xref{Printing Indices & Menus}, for information on how to print
9676 indices.
9677
9678 @menu
9679 * Index Entries:: Choose different words for index entries.
9680 * Predefined Indices:: Use different indices for different kinds
9681 of entries.
9682 * Indexing Commands:: How to make an index entry.
9683 * Combining Indices:: How to combine indices.
9684 * New Indices:: How to define your own indices.
9685 @end menu
9686
9687
9688 @node Index Entries
9689 @section Making Index Entries
9690 @cindex Index entries, making
9691 @cindex Entries, making index
9692
9693 When you are making index entries, it is good practice to think of the
9694 different ways people may look for something. Different people
9695 @emph{do not} think of the same words when they look something up. A
9696 helpful index will have items indexed under all the different words
9697 that people may use. For example, one reader may think it obvious that
9698 the two-letter names for indices should be listed under ``Indices,
9699 two-letter names'', since the word ``Index'' is the general concept.
9700 But another reader may remember the specific concept of two-letter
9701 names and search for the entry listed as ``Two letter names for
9702 indices''. A good index will have both entries and will help both
9703 readers.@refill
9704
9705 Like typesetting, the construction of an index is a highly skilled,
9706 professional art, the subtleties of which are not appreciated until you
9707 need to do it yourself.@refill
9708
9709 @xref{Printing Indices & Menus}, for information about printing an index
9710 at the end of a book or creating an index menu in an Info file.@refill
9711
9712
9713 @node Predefined Indices
9714 @section Predefined Indices
9715
9716 Texinfo provides six predefined indices. Here are their nominal
9717 meanings, abbreviations, and the corresponding index entry commands:
9718
9719 @table @samp
9720 @item cp
9721 @cindex @code{cp} (concept) index
9722 (@code{@@cindex}) concept index, for general concepts.
9723 @item fn
9724 @cindex @code{fn} (function) index
9725 (@code{@@findex}) function index, for function and function-like
9726 names (such as entry points of libraries).
9727 @item ky
9728 @cindex @code{ky} (keystroke) index
9729 (@code{@@kindex}) keystroke index, for keyboard commands.
9730 @item pg
9731 @cindex @code{pg} (program) index
9732 (@code{@@pindex}) program index, for names of programs.
9733 @item tp
9734 @cindex @code{tp} (data type) index
9735 (@code{@@tindex}) data type index, for type names (such as structures
9736 defined in header files).
9737 @item vr
9738 @cindex @code{vr} (variable) index
9739 (@code{@@vindex}) variable index, for variable names (such as global
9740 variables of libraries).
9741 @end table
9742
9743 @noindent
9744 Not every manual needs all of these, and most manuals use only two or
9745 three at most. The present manual, for example, has two indices: a
9746 concept index and an @@-command index (that is actually the function
9747 index but is called a command index in the chapter heading).
9748
9749 You are not required to use the predefined indices strictly for their
9750 canonical purposes. For example, suppose you wish to index some C
9751 preprocessor macros. You could put them in the function index along
9752 with actual functions, just by writing @code{@@findex} commands for
9753 them; then, when you print the ``Function Index'' as an unnumbered
9754 chapter, you could give it the title `Function and Macro Index' and
9755 all will be consistent for the reader.
9756
9757 On the other hand, it is best not to stray too far from the meaning of
9758 the predefined indices. Otherwise, in the event that your text is
9759 combined with other text from other manuals, the index entries will
9760 not match up. Instead, define your own new index (@pxref{New
9761 Indices}).
9762
9763 We recommend having a single index in the final document whenever
9764 possible, however many source indices you use, since then readers have
9765 only one place to look. Two or more source indices can be combined
9766 into one output index using the @code{@@synindex} or
9767 @code{@@syncodeindex} commands (@pxref{Combining Indices}).
9768
9769
9770 @node Indexing Commands
9771 @section Defining the Entries of an Index
9772 @cindex Defining indexing entries
9773 @cindex Index entries
9774 @cindex Entries for an index
9775 @cindex Specifying index entries
9776 @cindex Creating index entries
9777
9778 The data to make an index come from many individual indexing commands
9779 scattered throughout the Texinfo source file. Each command says to add
9780 one entry to a particular index; after formatting, the index will give
9781 the current page number or node name as the reference.@refill
9782
9783 An index entry consists of an indexing command at the beginning of a
9784 line followed, on the rest of the line, by the entry.@refill
9785
9786 For example, this section begins with the following five entries for
9787 the concept index:@refill
9788
9789 @example
9790 @@cindex Defining indexing entries
9791 @@cindex Index entries, defining
9792 @@cindex Entries for an index
9793 @@cindex Specifying index entries
9794 @@cindex Creating index entries
9795 @end example
9796
9797 Each predefined index has its own indexing command---@code{@@cindex}
9798 for the concept index, @code{@@findex} for the function index, and so
9799 on, as listed in the previous section.
9800
9801 @cindex Writing index entries
9802 @cindex Index entry writing
9803 Concept index entries consist of text. The best way to write an index
9804 is to choose entries that are terse yet clear. If you can do this,
9805 the index often looks better if the entries are not capitalized, but
9806 written just as they would appear in the middle of a sentence.
9807 (Capitalize proper names and acronyms that always call for upper case
9808 letters.) This is the case convention we use in most GNU manuals'
9809 indices.
9810
9811 If you don't see how to make an entry terse yet clear, make it longer
9812 and clear---not terse and confusing. If many of the entries are several
9813 words long, the index may look better if you use a different convention:
9814 to capitalize the first word of each entry. But do not capitalize a
9815 case-sensitive name such as a C or Lisp function name or a shell
9816 command; that would be a spelling error.
9817
9818 Whichever case convention you use, please use it consistently!
9819
9820 Entries in indices other than the concept index are symbol names in
9821 programming languages, or program names; these names are usually
9822 case-sensitive, so use upper and lower case as required for them.
9823
9824 @cindex Index font types
9825 By default, entries for a concept index are printed in a small roman
9826 font and entries for the other indices are printed in a small
9827 @code{@@code} font. You may change the way part of an entry is
9828 printed with the usual Texinfo commands, such as @code{@@file} for
9829 file names (@pxref{Marking Text}), and @code{@@r} for the normal roman
9830 font (@pxref{Fonts}).
9831
9832 @quotation Caution
9833 Do not use a colon in an index entry. In Info, a colon separates the
9834 menu entry name from the node name, so a colon in the entry itself
9835 confuses Info. @xref{Menu Parts}, for more information about the
9836 structure of a menu entry.
9837 @end quotation
9838
9839
9840 @node Combining Indices
9841 @section Combining Indices
9842 @cindex Combining indices
9843 @cindex Indices, combining them
9844
9845 Sometimes you will want to combine two disparate indices such as
9846 functions and concepts, perhaps because you have few enough entries
9847 that a separate index would look silly.
9848
9849 You could put functions into the concept index by writing
9850 @code{@@cindex} commands for them instead of @code{@@findex} commands,
9851 and produce a consistent manual by printing the concept index with the
9852 title `Function and Concept Index' and not printing the `Function
9853 Index' at all; but this is not a robust procedure. It works only if
9854 your document is never included as part of another document that is
9855 designed to have a separate function index; if your document were to
9856 be included with such a document, the functions from your document and
9857 those from the other would not end up together. Also, to make your
9858 function names appear in the right font in the concept index, you
9859 would need to enclose every one of them between the braces of
9860 @code{@@code}.
9861
9862 @menu
9863 * syncodeindex:: How to merge two indices, using @code{@@code}
9864 font for the merged-from index.
9865 * synindex:: How to merge two indices, using the
9866 default font of the merged-to index.
9867 @end menu
9868
9869 @node syncodeindex
9870 @subsection @code{@@syncodeindex}
9871 @findex syncodeindex
9872
9873 When you want to combine functions and concepts into one index, you
9874 should index the functions with @code{@@findex} and index the concepts
9875 with @code{@@cindex}, and use the @code{@@syncodeindex} command to
9876 redirect the function index entries into the concept index.@refill
9877
9878 The @code{@@syncodeindex} command takes two arguments; they are the name
9879 of the index to redirect, and the name of the index to redirect it to.
9880 The template looks like this:@refill
9881
9882 @example
9883 @@syncodeindex @var{from} @var{to}
9884 @end example
9885
9886 @cindex Predefined names for indices
9887 @cindex Two letter names for indices
9888 @cindex Indices, two letter names
9889 @cindex Names for indices
9890 For this purpose, the indices are given two-letter names:@refill
9891
9892 @table @samp
9893 @item cp
9894 concept index
9895 @item fn
9896 function index
9897 @item vr
9898 variable index
9899 @item ky
9900 key index
9901 @item pg
9902 program index
9903 @item tp
9904 data type index
9905 @end table
9906
9907 Write an @code{@@syncodeindex} command before or shortly after the
9908 end-of-header line at the beginning of a Texinfo file. For example,
9909 to merge a function index with a concept index, write the
9910 following:@refill
9911
9912 @example
9913 @@syncodeindex fn cp
9914 @end example
9915
9916 @noindent
9917 This will cause all entries designated for the function index to merge
9918 in with the concept index instead.@refill
9919
9920 To merge both a variables index and a function index into a concept
9921 index, write the following:@refill
9922
9923 @example
9924 @group
9925 @@syncodeindex vr cp
9926 @@syncodeindex fn cp
9927 @end group
9928 @end example
9929
9930 @cindex Fonts for indices
9931 The @code{@@syncodeindex} command puts all the entries from the `from'
9932 index (the redirected index) into the @code{@@code} font, overriding
9933 whatever default font is used by the index to which the entries are
9934 now directed. This way, if you direct function names from a function
9935 index into a concept index, all the function names are printed in the
9936 @code{@@code} font as you would expect.@refill
9937
9938 @node synindex
9939 @subsection @code{@@synindex}
9940 @findex synindex
9941
9942 The @code{@@synindex} command is nearly the same as the
9943 @code{@@syncodeindex} command, except that it does not put the
9944 `from' index entries into the @code{@@code} font; rather it puts
9945 them in the roman font. Thus, you use @code{@@synindex} when you
9946 merge a concept index into a function index.@refill
9947
9948 @xref{Printing Indices & Menus}, for information about printing an index
9949 at the end of a book or creating an index menu in an Info file.@refill
9950
9951
9952 @node New Indices
9953 @section Defining New Indices
9954 @cindex Defining new indices
9955 @cindex Indices, defining new
9956 @cindex New index defining
9957 @findex defindex
9958 @findex defcodeindex
9959
9960 In addition to the predefined indices, you may use the
9961 @code{@@defindex} and @code{@@defcodeindex} commands to define new
9962 indices. These commands create new indexing @@-commands with which
9963 you mark index entries. The @code{@@defindex} command is used like
9964 this:
9965
9966 @example
9967 @@defindex @var{name}
9968 @end example
9969
9970 The name of an index should be a two letter word, such as @samp{au}.
9971 For example:
9972
9973 @example
9974 @@defindex au
9975 @end example
9976
9977 This defines a new index, called the @samp{au} index. At the same
9978 time, it creates a new indexing command, @code{@@auindex}, that you
9979 can use to make index entries. Use this new indexing command just as
9980 you would use a predefined indexing command.
9981
9982 For example, here is a section heading followed by a concept index
9983 entry and two @samp{au} index entries.
9984
9985 @example
9986 @@section Cognitive Semantics
9987 @@cindex kinesthetic image schemas
9988 @@auindex Johnson, Mark
9989 @@auindex Lakoff, George
9990 @end example
9991
9992 @noindent
9993 (Evidently, @samp{au} serves here as an abbreviation for ``author''.)
9994
9995 In general, Texinfo constructs the new indexing command by
9996 concatenating the name of the index with @samp{index}; thus, defining
9997 an @samp{xy} index leads to the automatic creation of an
9998 @code{@@xyindex} command.
9999
10000 Use the @code{@@printindex} command to print the index, as you do with
10001 the predefined indices. For example:
10002
10003 @example
10004 @group
10005 @@node Author Index
10006 @@unnumbered Author Index
10007
10008 @@printindex au
10009 @end group
10010 @end example
10011
10012 The @code{@@defcodeindex} is like the @code{@@defindex} command,
10013 except that, in the printed output, it prints entries in an
10014 @code{@@code} font by default instead of a roman font.
10015
10016 You should define new indices before the end-of-header line of a
10017 Texinfo file, and (of course) before any @code{@@synindex} or
10018 @code{@@syncodeindex} commands (@pxref{Texinfo File Header}).
10019
10020
10021 @node Insertions
10022 @chapter Special Insertions
10023 @cindex Inserting special characters and symbols
10024 @cindex Special insertions
10025
10026 Texinfo provides several commands for inserting characters that have
10027 special meaning in Texinfo, such as braces, and for other graphic
10028 elements that do not correspond to simple characters you can type.
10029
10030 @iftex
10031 These are:
10032
10033 @itemize @bullet
10034 @item @samp{@@} and braces and commas.
10035 @item Whitespace within and around a sentence.
10036 @item Accents.
10037 @item Dots and bullets.
10038 @item The @TeX{} logo and the copyright symbol.
10039 @item The euro and pounds currency symbols.
10040 @item The degrees symbol.
10041 @item The minus sign.
10042 @item Mathematical expressions.
10043 @item Glyphs for evaluation, macros, errors, etc.
10044 @item Footnotes.
10045 @item Images.
10046 @end itemize
10047 @end iftex
10048
10049 @menu
10050 * Atsign Braces Comma:: Inserting @@ and @{@} and ,.
10051 * Inserting Quote Characters:: Inserting left and right quotes, in code.
10052 * Inserting Space:: How to insert the right amount of space
10053 within a sentence.
10054 * Inserting Accents:: How to insert accents and special characters.
10055 * Inserting Quotation Marks:: How to insert quotation marks.
10056 * Dots Bullets:: How to insert dots and bullets.
10057 * TeX and copyright:: How to insert the @TeX{} logo
10058 and the copyright symbol.
10059 * euro:: How to insert the Euro currency symbol.
10060 * pounds:: How to insert the pounds currency symbol.
10061 * textdegree:: How to insert the degrees symbol.
10062 * minus:: How to insert a minus sign.
10063 * geq leq:: How to insert greater/less-than-or-equal signs.
10064 * math:: How to format a mathematical expression.
10065 * Click Sequences:: Inserting GUI usage sequences.
10066 * Glyphs:: How to indicate results of evaluation,
10067 expansion of macros, errors, etc.
10068 @end menu
10069
10070
10071 @node Atsign Braces Comma
10072 @section Inserting @@ and @{@} and @comma{}
10073 @cindex Special characters, inserting
10074 @cindex Commands to insert special characters
10075
10076 @samp{@@} and curly braces are special characters in Texinfo. To insert
10077 these characters so they appear in text, you must put an @samp{@@} in
10078 front of these characters to prevent Texinfo from misinterpreting
10079 them.
10080
10081 The comma `,' is a special character only in one uncommon context:
10082 it separates arguments to commands that take multiple arguments.
10083
10084 @menu
10085 * Inserting an Atsign::
10086 * Inserting Braces::
10087 * Inserting a Comma::
10088 @end menu
10089
10090
10091 @node Inserting an Atsign
10092 @subsection Inserting `@@' with @code{@@@@}
10093 @findex @@ @r{(literal @samp{@@})}
10094 @cindex Inserting @@ @r{(literal @samp{@@})}
10095
10096 @code{@@@@} stands for a single @samp{@@} in either printed or Info
10097 output.
10098
10099 Do not put braces after an @code{@@@@} command.
10100
10101
10102 @node Inserting Braces
10103 @subsection Inserting `@{' and `@}' with @code{@@@{} and @code{@@@}}
10104 @cindex Braces, inserting
10105 @findex @{ @r{(literal @samp{@{})}
10106 @findex @} @r{(literal @samp{@}})}
10107
10108 @code{@@@{} stands for a single @samp{@{} in either printed or Info
10109 output.
10110
10111 @code{@@@}} stands for a single @samp{@}} in either printed or Info
10112 output.
10113
10114 Do not put braces after either an @code{@@@{} or an @code{@@@}}
10115 command.
10116
10117
10118 @node Inserting a Comma
10119 @subsection Inserting `,' with @code{@@comma@{@}}
10120 @cindex Commas, inserting
10121 @findex comma
10122
10123 Ordinarily, a comma `,' is a normal character that can be simply typed
10124 in your input where you need it.
10125
10126 However, Texinfo uses the comma as a special character in one uncommon
10127 context: some commands, such as @code{@@acronym} (@pxref{acronym}) and
10128 @code{@@xref} (@pxref{Cross References}), as well as user-defined
10129 macros (@pxref{Defining Macros}), can take more than one argument. In
10130 these cases, the comma character is used to separate arguments.
10131
10132 Since a comma character would confuse Texinfo's parsing for these
10133 commands, you must use the command @samp{@@comma@{@}} instead if you want
10134 to pass an actual comma. Here are some examples:
10135
10136 @example
10137 @@acronym@{ABC, A Bizarre @@comma@{@}@}
10138 @@xref@{Comma,, The @@comma@{@} symbol@}
10139 @@mymac@{One argument@@comma@{@} containing a comma@}
10140 @end example
10141
10142 Although @comma{} can be used nearly anywhere, there is no need for it
10143 anywhere except in this unusual case.
10144
10145
10146 @node Inserting Quote Characters
10147 @section Inserting Quote Characters
10148
10149 @cindex Inserting quote characters
10150 @cindex Quote characters, inserting
10151
10152 As explained in the early section on general Texinfo input conventions
10153 (@pxref{Conventions}), Texinfo source files use the ASCII character
10154 @code{`} (96 decimal) to produce a left quote (`), and ASCII @code{'}
10155 (39 decimal) to produce a right quote ('). Doubling these input
10156 characters (@code{``} and @code{''}) produces double quotes (`` and
10157 ''). These are the conventions used by @TeX{}.
10158
10159 This works all right for text. However, in examples of computer code,
10160 readers are especially likely to cut and paste the text
10161 verbatim---and, unfortunately, some document viewers will mangle these
10162 characters. (The free PDF reader @command{xpdf} works fine, but other
10163 PDF readers, both free and nonfree, have problems.)
10164
10165 If this is a concern for your document, Texinfo provides two special
10166 settings via @code{@@set}:
10167
10168 @table @code
10169 @item @@set txicodequoteundirected
10170 causes the output for the @code{'} character to be the undirected
10171 single quote, like this:
10172 @set txicodequoteundirected
10173 @code{'}.
10174 @clear txicodequoteundirected
10175
10176 @item @@set txicodequotebacktick
10177 Cause the output for the @code{`} character to be the standalone grave
10178 accent, like this:
10179 @set txicodequotebacktick
10180 @code{`}.
10181 @clear txicodequotebacktick
10182
10183 @end table
10184
10185 @code{xyza`'bc}
10186
10187 If you want these settings for only part of the document,
10188 @code{@@clear} will restore the normal behavior, as in
10189 @code{@@clear@tie{}txicodequoteundirected}.
10190
10191 These settings affect @code{@@code}, @code{@@example}, and
10192 @code{@@verbatim}; they do not affect @code{@@samp}. (@xref{Useful
10193 Highlighting}.)
10194
10195
10196 @node Inserting Space
10197 @section Inserting Space
10198
10199 @cindex Inserting space
10200 @cindex Spacing, inserting
10201 The following sections describe commands that control spacing of various
10202 kinds within and after sentences.
10203
10204 @menu
10205 * Not Ending a Sentence:: Sometimes a . doesn't end a sentence.
10206 * Ending a Sentence:: Sometimes it does.
10207 * Multiple Spaces:: Inserting multiple spaces.
10208 * frenchspacing:: Specifying end-of-sentence spacing.
10209 * dmn:: How to format a dimension.
10210 @end menu
10211
10212
10213 @node Not Ending a Sentence
10214 @subsection Not Ending a Sentence
10215
10216 @cindex Not ending a sentence
10217 @cindex Sentence non-ending punctuation
10218 @cindex Periods, inserting
10219 Depending on whether a period or exclamation point or question mark is
10220 inside or at the end of a sentence, less or more space is inserted after
10221 a period in a typeset manual. Since it is not always possible
10222 to determine when a period ends a sentence and when it is used
10223 in an abbreviation, special commands are needed in some circumstances.
10224 Usually, Texinfo can guess how to handle periods, so you do not need to
10225 use the special commands; you just enter a period as you would if you
10226 were using a typewriter, which means you put two spaces after the
10227 period, question mark, or exclamation mark that ends a sentence.
10228
10229 @findex <colon> @r{(suppress end-of-sentence space)}
10230 Use the @code{@@:}@: command after a period, question mark,
10231 exclamation mark, or colon that should not be followed by extra space.
10232 For example, use @code{@@:}@: after periods that end abbreviations
10233 which are not at the ends of sentences.
10234
10235 For example,
10236
10237 @example
10238 foo vs.@@: bar
10239 foo vs. bar
10240 @end example
10241
10242 @noindent
10243 @ifnottex
10244 produces
10245 @end ifnottex
10246 @iftex
10247 produces the following. If you look carefully at this printed output,
10248 you will see a little extraneous space after @samp{vs.}@: in the second
10249 line.
10250 @end iftex
10251
10252 @quotation
10253 foo vs.@: bar @*
10254 foo vs. bar
10255 @end quotation
10256
10257 @noindent
10258 @code{@@:} has no effect on the Info and HTML output. In Docbook and
10259 XML, the previous punctuation character (.?!:) is output as an entity
10260 instead of as the normal character: @samp{&period; &quest; &excl;
10261 &colon;}. This gives further processors a chance to notice and not
10262 add the usual extra space.
10263
10264 Do not put braces after @code{@@:} (or any non-alphabetic command).
10265
10266
10267 @node Ending a Sentence
10268 @subsection Ending a Sentence
10269
10270 @cindex Ending a Sentence
10271 @cindex Sentence ending punctuation
10272
10273 @findex . @r{(end of sentence)}
10274 @findex ! @r{(end of sentence)}
10275 @findex ? @r{(end of sentence)}
10276 Use @code{@@.}@: instead of a period, @code{@@!}@: instead of an
10277 exclamation point, and @code{@@?}@: instead of a question mark at the end
10278 of a sentence that ends with a capital letter. Otherwise, @TeX{}
10279 will think the letter is an abbreviation and will not insert the correct
10280 end-of-sentence spacing. Here is an example:
10281
10282 @example
10283 Give it to M.I.B. and to M.E.W@@. Also, give it to R.J.C@@.
10284 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
10285 @end example
10286
10287 @noindent
10288 @ifnottex
10289 produces
10290 @end ifnottex
10291 @iftex
10292 produces the following. If you look carefully at this printed output,
10293 you will see a little more whitespace after the @samp{W} in the first
10294 line.
10295 @end iftex
10296
10297 @quotation
10298 Give it to M.I.B. and to M.E.W@. Also, give it to R.J.C@.@*
10299 Give it to M.I.B. and to M.E.W. Also, give it to R.J.C.
10300 @end quotation
10301
10302 In the Info file output, @code{@@.}@: is equivalent to a simple
10303 @samp{.}; likewise for @code{@@!}@: and @code{@@?}@:.
10304
10305 The meanings of @code{@@:} and @code{@@.}@: in Texinfo are designed to
10306 work well with the XEmacs sentence motion commands (@pxref{Sentences,,,
10307 xemacs, XEmacs User's Manual}).
10308
10309 Do not put braces after any of these commands.
10310
10311
10312 @node Multiple Spaces
10313 @subsection Multiple Spaces
10314
10315 @cindex Multiple spaces
10316 @cindex Whitespace, inserting
10317 @cindex Space, inserting horizontal
10318 @findex <space>
10319 @findex <tab>
10320 @findex <newline>
10321
10322 Ordinarily, @TeX{} collapses multiple whitespace characters (space, tab,
10323 and newline) into a single space. Info output, on the other hand,
10324 preserves whitespace as you type it, except for changing a newline into
10325 a space; this is why it is important to put two spaces at the end of
10326 sentences in Texinfo documents.
10327
10328 Occasionally, you may want to actually insert several consecutive
10329 spaces, either for purposes of example (what your program does with
10330 multiple spaces as input), or merely for purposes of appearance in
10331 headings or lists. Texinfo supports three commands:
10332 @code{@@@kbd{SPACE}}, @code{@@@kbd{TAB}}, and @code{@@@kbd{NL}}, all of
10333 which insert a single space into the output. (Here,
10334 @code{@@@kbd{SPACE}} represents an @samp{@@} character followed by a
10335 space, i.e., @samp{@@ }, and @kbd{TAB} and @kbd{NL} represent the tab
10336 character and end-of-line, i.e., when @samp{@@} is the last character on
10337 a line.)
10338
10339 For example,
10340 @example
10341 Spacey@@ @@ @@ @@
10342 example.
10343 @end example
10344
10345 @noindent
10346 produces
10347
10348 @example
10349 Spacey@ @ @ @
10350 example.
10351 @end example
10352
10353 Other possible uses of @code{@@@kbd{SPACE}} have been subsumed by
10354 @code{@@multitable} (@pxref{Multi-column Tables}).
10355
10356 Do not follow any of these commands with braces.
10357
10358 To produce a non-breakable space, see @ref{tie, @code{@@tie}}.
10359
10360
10361 @node frenchspacing
10362 @subsection @code{@@frenchspacing} @var{val}: Control sentence spacing
10363 @findex frenchspacing
10364 @cindex French spacing
10365 @cindex Sentences, spacing after
10366 @cindex Space, after sentences
10367
10368 In American typography, it is traditional and correct to put extra
10369 space at the end of a sentence, after a semi-colon, and so on. This
10370 is the default in Texinfo. In French typography (and many others),
10371 this extra space is wrong; all spaces are uniform.
10372
10373 Therefore Texinfo provides the @code{@@frenchspacing} command to
10374 control the spacing after punctuation. It reads the rest of the line
10375 as its argument, which must be the single word @samp{on} or @samp{off}
10376 (always these words, regardless of the language) of the document.
10377 Here is an example:
10378
10379 @example
10380 @@frenchspacing on
10381 This is text. Two sentences. Three sentences. French spacing.
10382
10383 @@frenchspacing off
10384 This is text. Two sentences. Three sentences. Non-French spacing.
10385 @end example
10386
10387 @noindent produces (there will be no difference in Info):
10388
10389 @frenchspacing on
10390 This is text. Two sentences. Three sentences. French spacing.
10391
10392 @frenchspacing off
10393 This is text. Two sentences. Three sentences. Non-French spacing.
10394
10395 @code{@@frenchspacing} mainly affects the printed output, including
10396 the output after @code{@@.}, @code{@@!}, and @code{@@?} (@pxref{Ending
10397 a Sentence}).
10398
10399 In Info, usually space characters in the input are written unaltered
10400 to the output, and @code{@@frenchspacing} does not change this. It
10401 does change the one case where @command{makeinfo} outputs a space on
10402 its own: when a sentence ends at a newline in the source. Here's an
10403 example:
10404
10405 @example
10406 Some sentence.
10407 Next sentence.
10408 @end example
10409
10410 @noindent produces in Info output, with @code{@@frenchspacing off}
10411 (the default), two spaces between the sentences:
10412
10413 @example
10414 Some sentence. Next sentence.
10415 @end example
10416
10417 @noindent With @code{@@frenchspacing on}, @command{makeinfo} outputs
10418 only a single space:
10419
10420 @example
10421 Some sentence. Next sentence.
10422 @end example
10423
10424 @code{@@frenchspacing} has no effect on the HTML or Docbook output;
10425 for XML, it outputs a transliteration of itself (@pxref{Output
10426 Formats}).
10427
10428
10429 @node dmn
10430 @subsection @code{@@dmn}@{@var{dimension}@}: Format a Dimension
10431 @cindex Thin space between number, dimension
10432 @cindex Dimension formatting
10433 @cindex Format a dimension
10434 @findex dmn
10435
10436 At times, you may want to write @samp{12@dmn{pt}} or
10437 @samp{8.5@dmn{in}} with little or no space between the number and the
10438 abbreviation for the dimension. You can use the @code{@@dmn} command
10439 to do this. On seeing the command, @TeX{} inserts just enough space
10440 for proper typesetting; the Info formatting commands insert no space
10441 at all, since the Info file does not require it.
10442
10443 To use the @code{@@dmn} command, write the number and then follow it
10444 immediately, with no intervening space, by @code{@@dmn}, and then by
10445 the dimension within braces. For example,
10446
10447 @example
10448 A4 paper is 8.27@@dmn@{in@} wide.
10449 @end example
10450
10451 @noindent
10452 produces
10453
10454 @quotation
10455 A4 paper is 8.27@dmn{in} wide.
10456 @end quotation
10457
10458 Not everyone uses this style. Some people prefer @w{@samp{8.27 in.@@:}}
10459 or @w{@samp{8.27 inches}} to @samp{8.27@@dmn@{in@}} in the Texinfo file.
10460 In these cases, however, the formatters may insert a line break between
10461 the number and the dimension, so use @code{@@w} (@pxref{w}). Also, if
10462 you write a period after an abbreviation within a sentence, you should
10463 write @samp{@@:} after the period to prevent @TeX{} from inserting extra
10464 whitespace, as shown here. @xref{Not Ending a Sentence}.
10465
10466
10467 @node Inserting Accents
10468 @section Inserting Accents
10469
10470 @cindex Inserting accents
10471 @cindex Accents, inserting
10472 @cindex Floating accents, inserting
10473
10474 Here is a table with the commands Texinfo provides for inserting
10475 floating accents. They all need an argument, the character to accent,
10476 which can either be given in braces as usual (@code{@@'@{e@}}), or, as
10477 a special case, the braces can be omitted, in which case the argument
10478 is the next character (@code{@@'e}). This is to make the source as
10479 convenient as possible to type and read, since accented characters are
10480 very common in some languages.
10481
10482 If the command is alphabetic, such as @code{@@dotaccent}, then there
10483 must be a space between the command name and argument if braces are
10484 not used. If the command is non-alphabetic, such as @code{@@'}, then
10485 there must @emph{not} be a space; the argument is the very next
10486 character.
10487
10488 Exception: the argument to @code{@@tieaccent} must be enclosed in
10489 braces (since it is two characters instead of one).
10490
10491 @findex documentencoding
10492 To get the true accented characters output in Info, not just the ASCII
10493 transliterations, it is necessary to specify @code{@@documentencoding}
10494 with an encoding which supports the required characters
10495 (@pxref{documentencoding,,@code{@@documentencoding}}). In this case,
10496 you can also use non-ASCII (e.g., pre-accented) characters in the
10497 source file.
10498
10499 @findex " @r{(umlaut accent)}
10500 @cindex Umlaut accent
10501 @findex ' @r{(umlaut accent)}
10502 @cindex Acute accent
10503 @findex = @r{(macron accent)}
10504 @cindex Macron accent
10505 @findex ^ @r{(circumflex accent)}
10506 @cindex Circumflex accent
10507 @findex ` @r{(grave accent)}
10508 @cindex Grave accent
10509 @findex ~ @r{(tilde accent)}
10510 @cindex Tilde accent
10511 @findex , @r{(cedilla accent)}
10512 @cindex Cedilla accent
10513 @findex dotaccent
10514 @cindex Dot accent
10515 @findex H @r{(Hungarian umlaut accent)}
10516 @cindex Hungarian umlaut accent
10517 @findex ringaccent
10518 @cindex Ring accent
10519 @findex tieaccent
10520 @cindex Tie-after accent
10521 @findex u @r{(breve accent)}
10522 @cindex Breve accent
10523 @findex ubaraccent
10524 @cindex Underbar accent
10525 @findex udotaccent
10526 @cindex Underdot accent
10527 @findex v @r{(check accent)}
10528 @cindex Hacek accent
10529 @cindex Check accent
10530 @cindex Caron accent
10531 @multitable {@t{@@questiondown@{@}}} {Output} {hacek/check/caron accent}
10532 @headitem Command @tab Output @tab What
10533 @item @t{@@"o} @tab @"o @tab umlaut accent
10534 @item @t{@@'o} @tab @'o @tab acute accent
10535 @item @t{@@,@{c@}} @tab @,{c} @tab cedilla accent
10536 @item @t{@@=o} @tab @=o @tab macron/overbar accent
10537 @item @t{@@^o} @tab @^o @tab circumflex accent
10538 @item @t{@@`o} @tab @`o @tab grave accent
10539 @item @t{@@~o} @tab @~o @tab tilde accent
10540 @item @t{@@dotaccent@{o@}} @tab @dotaccent{o} @tab overdot accent
10541 @item @t{@@H@{o@}} @tab @H{o} @tab long Hungarian umlaut
10542 @item @t{@@ringaccent@{o@}} @tab @ringaccent{o} @tab ring accent
10543 @item @t{@@tieaccent@{oo@}} @tab @tieaccent{oo} @tab tie-after accent
10544 @item @t{@@u@{o@}} @tab @u{o} @tab breve accent
10545 @item @t{@@ubaraccent@{o@}} @tab @ubaraccent{o} @tab underbar accent
10546 @item @t{@@udotaccent@{o@}} @tab @udotaccent{o} @tab underdot accent
10547 @item @t{@@v@{o@}} @tab @v{o} @tab hacek/check/caron accent
10548 @end multitable
10549
10550 This table lists the Texinfo commands for inserting other characters
10551 commonly used in languages other than English.
10552
10553 @findex questiondown
10554 @cindex @questiondown{}
10555 @findex exclamdown
10556 @cindex @exclamdown{}
10557 @findex aa
10558 @cindex @aa{}
10559 @findex AA
10560 @cindex @AA{}
10561 @findex ae
10562 @cindex @ae{}
10563 @findex AE
10564 @cindex @AE{}
10565 @findex dotless
10566 @cindex @dotless{i} (dotless i)
10567 @cindex @dotless{j} (dotless j)
10568 @cindex Dotless i, j
10569 @findex l
10570 @cindex @l{}
10571 @findex L
10572 @cindex @L{}
10573 @findex o
10574 @cindex @o{}
10575 @findex O
10576 @cindex @O{}
10577 @findex oe
10578 @cindex @oe{}
10579 @findex OE
10580 @cindex @OE{}
10581 @cindex Romance ordinals
10582 @cindex Ordinals, Romance
10583 @cindex Feminine ordinal
10584 @findex ordf
10585 @cindex @ordf{}
10586 @cindex Masculine ordinal
10587 @findex ordm
10588 @cindex @ordm{}
10589 @findex ss
10590 @cindex @ss{}
10591 @cindex Es-zet
10592 @cindex Sharp S
10593 @cindex German S
10594 @multitable {@t{@@questiondown@{@}}} {oe OE} {es-zet or sharp S}
10595 @item @t{@@exclamdown@{@}} @tab @exclamdown{} @tab upside-down !
10596 @item @t{@@questiondown@{@}} @tab @questiondown{} @tab upside-down ?
10597 @item @t{@@aa@{@} @@AA@{@}} @tab @aa{} @AA{} @tab a,A with circle
10598 @item @t{@@ae@{@} @@AE@{@}} @tab @ae{} @AE{} @tab ae,AE ligatures
10599 @item @t{@@dotless@{i@}} @tab @dotless{i} @tab dotless i
10600 @item @t{@@dotless@{j@}} @tab @dotless{j} @tab dotless j
10601 @item @t{@@l@{@} @@L@{@}} @tab @l{} @L{} @tab suppressed-L,l
10602 @item @t{@@o@{@} @@O@{@}} @tab @o{} @O{} @tab O,o with slash
10603 @item @t{@@oe@{@} @@OE@{@}} @tab @oe{} @OE{} @tab oe,OE ligatures
10604 @item @t{@@ordf@{@} @@ordm@{@}} @tab @ordf{} @ordm{} @tab Spanish ordinals
10605 @item @t{@@ss@{@}} @tab @ss{} @tab es-zet or sharp S
10606 @end multitable
10607
10608
10609 @node Inserting Quotation Marks
10610 @section Inserting Quotation Marks
10611 @cindex Inserting quotation marks
10612 @cindex Quotation marks, inserting
10613
10614 @cindex Quotation characters (`'), in source
10615 Use doubled single-quote characters to begin and end quotations:
10616 @w{@t{`@w{}`@dots{}'@w{}'}}. @TeX{} converts two single quotes to
10617 left- and right-hand doubled quotation marks,
10618 @c this comes out as "like this" in Info, which is just confusing.
10619 @iftex
10620 ``like this'',
10621 @end iftex
10622 and Info converts doubled single-quote characters to ASCII
10623 double-quotes: @w{@t{`@w{}`@dots{}'@w{}'}} becomes @w{@t{"@dots{}"}}.
10624
10625 You may occasionally need to produce two consecutive single quotes;
10626 for example, in documenting a computer language such as Maxima where
10627 @t{'@w{}'} is a valid command. You can do this with the input
10628 @t{'@@w@{@}'}; the empty @code{@@w} command stops the combination into
10629 the double-quote characters.
10630
10631 @cindex Unicode quotation characters
10632 @cindex Grave accent, vs. left quote
10633 The left quote character (@t{`}, ASCII code 96) used in Texinfo is a
10634 grave accent in ANSI and ISO character set standards. We use it as a
10635 quote character because that is how @TeX{} is set up, by default.
10636
10637 Texinfo supports several other quotation marks used in languages other
10638 than English. Below is a table with the commands Texinfo provides for
10639 inserting quotation marks.
10640
10641 @findex documentencoding
10642 @cindex UTF-8
10643 @cindex ISO 8859-15
10644 @cindex Latin 9
10645 @cindex ISO 8859-1
10646 @cindex Latin 1
10647 In order to get the symbols for the quotation marks in encoded Info
10648 output, it is necessary to specify @code{@@documentencoding UTF-8}.
10649 (@xref{documentencoding,,@code{@@documentencoding}}.) Double
10650 guillemets are also present in ISO 8859-1 (aka Latin@tie{}1) and ISO
10651 8859-15 (aka Latin@tie{}9).
10652
10653 @cindex European Computer Modern fonts
10654 @cindex EC fonts
10655 The standard @TeX{} fonts support the usual quotation marks used in
10656 English (the ones produced with single and doubled ASCII
10657 single-quotes). For the other quotation marks, @TeX{} uses European
10658 Computer Modern (EC) fonts (@file{ecrm1000} and other variants).
10659 These fonts are freely available, of course; you can download them
10660 from @url{http://@/www.ctan.org/@/tex-archive/@/fonts/ec}, among other
10661 places.
10662
10663 @cindex CM-Super fonts
10664 The free EC fonts are bitmap fonts created with Metafont. Especially
10665 for on-line viewing, Type@tie{}1 (vector) versions of the fonts are
10666 preferable; these are available in the CM-Super font package
10667 (@url{http://@/www.ctan.org/@/tex-archive/@/fonts/@/ps-type1/@/cm-super}).
10668
10669 Both distributions include installation instructions.
10670
10671 @cindex Single quotation marks
10672 @cindex Double quotation marks
10673 @cindex Left quotation marks
10674 @cindex Right quotation marks
10675 @findex quotedblleft
10676 @cindex ``
10677 @findex quoteleft
10678 @cindex `
10679 @findex quotedblright
10680 @cindex ''
10681 @findex quoteright
10682 @cindex '
10683 @cindex Double low-9 quotation mark
10684 @cindex Single low-9 quotation mark
10685 @findex quotedblbase
10686 @cindex @quotedblbase{} (double low-9 quotation mark)
10687 @findex quotesinglbase
10688 @cindex @quotesinglbase{} (single low-9 quotation mark)
10689 @cindex Angle quotation marks
10690 @cindex Guillemets
10691 @cindex Guillemots
10692 @cindex French quotation marks
10693 @cindex Quotation marks, French
10694 @cindex German quotation marks
10695 @cindex Quotation marks, German
10696 @cindex Double guillemets
10697 @cindex Single guillemets
10698 @cindex Double angle quotation marks
10699 @cindex Single angle quotation marks
10700 @cindex Left-pointing angle quotation marks
10701 @cindex Right-pointing angle quotation marks
10702 @cindex Double left-pointing angle quotation mark
10703 @cindex Double right-pointing angle quotation mark
10704 @cindex Single left-pointing angle quotation mark
10705 @cindex Single right-pointing angle quotation mark
10706 @findex guillemetleft
10707 @findex guillemotleft
10708 @cindex @guillemetleft{}
10709 @findex guillemetright
10710 @findex guillemotright
10711 @cindex @guillemetright{}
10712 @findex guilsinglleft
10713 @cindex @guilsinglleft{}
10714 @findex guilsinglright
10715 @cindex @guilsinglright{}
10716 @multitable {@t{@@quotedblright@{@} '@w{}'}} {Glyph} {Right-pointing double angle quotation mark (U+00BB)}
10717 @headitem Command @tab Glyph @tab Unicode name (point)
10718 @item @verb{.@quotedblleft{} ``.} @tab @quotedblleft{} @tab Left double quotation mark (U+201C)
10719 @item @verb{.@quotedblright{} ''.} @tab @quotedblright{} @tab Right double quotation mark (U+201D)
10720 @item @verb{.@quoteleft{} `.} @tab @quoteleft{} @tab Left single quotation mark (U+2018)
10721 @item @verb{.@quoteright{} '.} @tab @quoteright{} @tab Right single quotation mark (U+2019)
10722 @item @t{@@quotedblbase@{@}} @tab @quotedblbase{} @tab Double low-9 quotation mark (U+201E)
10723 @item @t{@@quotesinglbase@{@}} @tab @quotesinglbase{} @tab Single low-9 quotation mark (U+201A)
10724 @item @t{@@guillemetleft@{@}} @tab @guillemetleft{} @tab Left-pointing double angle quotation mark (U+00AB)
10725 @item @t{@@guillemetright@{@}} @tab @guillemetright{} @tab Right-pointing double angle quotation mark (U+00BB)
10726 @item @t{@@guilsinglleft@{@}} @tab @guilsinglleft{} @tab Single left-pointing angle quotation mark (U+2039)
10727 @item @t{@@guilsinglright@{@}} @tab @guilsinglright{} @tab Single right-pointing angle quotation mark (U+203A)
10728 @end multitable
10729
10730 For the double angle quotation marks, Adobe and @LaTeX{} glyph names
10731 are also supported: @code{@@guillemotleft} and
10732 @code{@@guillemotright}. These names are actually incorrect; a
10733 ``guillemot'' is a bird species (a type of auk).
10734
10735 Traditions for quotation mark usage vary to a great extent between
10736 languages (@url{http://@/en.wikipedia.org/@/wiki/@/Quotation_mark%2C_non-English_usage@/#Overview}).
10737 Texinfo does not provide commands for typesetting quotation marks
10738 according to the numerous traditions. Therefore, you have to choose
10739 the commands appropriate for the language of your manual. Sometimes
10740 aliases (@pxref{alias,,@code{@@alias}}) can simplify the usage and
10741 make the source code more readable. For example, in German,
10742 @code{@@quotedblbase} is used for the left double quote, and the right
10743 double quote is actually @code{@@quotedblleft}, which is
10744 counter-intuitive. Thus, in this case the following aliases would be
10745 convenient:
10746
10747 @example
10748 @@alias lgqq = quotedblbase
10749 @@alias rgqq = quotedblleft
10750 @end example
10751
10752
10753 @node Dots Bullets
10754 @section Inserting Ellipsis and Bullets
10755 @cindex Dots, inserting
10756 @cindex Bullets, inserting
10757 @cindex Ellipsis, inserting
10758 @cindex Inserting ellipsis
10759 @cindex Inserting dots
10760 @cindex Special typesetting commands
10761 @cindex Typesetting commands for dots, etc.
10762
10763 An @dfn{ellipsis} (a line of dots) is not typeset as a string of
10764 periods, so a special command is used for ellipsis in Texinfo. The
10765 @code{@@bullet} command is special, too. Each of these commands is
10766 followed by a pair of braces, @samp{@{@}}, without any whitespace
10767 between the name of the command and the braces. (You need to use braces
10768 with these commands because you can use them next to other text; without
10769 the braces, the formatters would be confused. @xref{Command Syntax, ,
10770 @@-Command Syntax}, for further information.)@refill
10771
10772 @menu
10773 * dots:: How to insert dots @dots{}
10774 * bullet:: How to insert a bullet.
10775 @end menu
10776
10777
10778 @node dots
10779 @subsection @code{@@dots}@{@} (@dots{}) and @code{@@enddots}@{@} (@enddots{})
10780 @findex dots
10781 @findex enddots
10782 @cindex Inserting dots
10783 @cindex Dots, inserting
10784
10785 Use the @code{@@dots@{@}} command to generate an ellipsis, which is
10786 three dots in a row, appropriately spaced @dots{} like so. Do
10787 not simply write three periods in the input file; that would work for
10788 the Info file output, but would produce the wrong amount of space
10789 between the periods in the printed manual.
10790
10791 Similarly, the @code{@@enddots@{@}} command generates an
10792 end-of-sentence ellipsis, which has different spacing afterwards,
10793 @enddots{} Look closely to see the difference.
10794
10795 @iftex
10796 Here is an ellipsis: @dots{}
10797 Here are three periods in a row: ...
10798
10799 In printed output, the three periods in a row are much closer together than
10800 the dots in the ellipsis.
10801 @end iftex
10802
10803
10804 @node bullet
10805 @subsection @code{@@bullet}@{@} (@bullet{})
10806 @findex bullet
10807
10808 Use the @code{@@bullet@{@}} command to generate a large round dot, or
10809 the closest possible thing to one. In Info, an asterisk is used.@refill
10810
10811 Here is a bullet: @bullet{}
10812
10813 When you use @code{@@bullet} in @code{@@itemize}, you do not need to
10814 type the braces, because @code{@@itemize} supplies them.
10815 (@xref{itemize, , @code{@@itemize}}.)@refill
10816
10817
10818 @node TeX and copyright
10819 @section Inserting @TeX{} and Legal Symbols: @copyright{}, @registeredsymbol{}
10820
10821 The logo `@TeX{}' is typeset in a special fashion and it needs an
10822 @@-command. The copyright and registered symbols, `@copyright{}' and
10823 `@registeredsymbol{}', is also special. Each of these commands is
10824 followed by a pair of braces, @samp{@{@}}, without any whitespace
10825 between the name of the command and the braces.
10826
10827 @menu
10828 * tex:: The @TeX{} logos.
10829 * copyright symbol:: The copyright symbol (c in a circle).
10830 * registered symbol:: The registered symbol (R in a circle).
10831 @end menu
10832
10833
10834 @node tex
10835 @subsection @code{@@TeX}@{@} (@TeX{}) and @code{@@LaTeX}@{@} (@LaTeX{})
10836 @findex TeX
10837 @findex LaTeX
10838 @cindex Logos, @TeX{}
10839 @cindex @TeX{} logo
10840 @cindex @LaTeX{} logo
10841
10842 Use the @code{@@TeX@{@}} command to generate `@TeX{}'. In a printed
10843 manual, this is a special logo that is different from three ordinary
10844 letters. In Info, it just looks like @samp{TeX}.
10845
10846 Similarly, use the @code{@@LaTeX@{@}} command to generate `@LaTeX{}',
10847 which is even more special in printed manuals (and different from the
10848 incorrect @code{La@@TeX@{@}}. In Info, the result is just
10849 @samp{LaTeX}. (@LaTeX{} is another macro package built on top of
10850 @TeX{}, very loosely analogous to Texinfo in that it emphasizes
10851 logical structure, but much (much) larger.)
10852
10853 The spelling of these commands are unusual among Texinfo commands in
10854 that they use both uppercase and lowercase letters.
10855
10856
10857 @node copyright symbol
10858 @subsection @code{@@copyright@{@}} (@copyright{})
10859 @findex copyright
10860 @cindex Copyright symbol
10861
10862 Use the @code{@@copyright@{@}} command to generate the copyright
10863 symbol, `@copyright{}'. Where possible, this is a @samp{c}
10864 inside a circle; in Info, this is @samp{(C)}.
10865
10866
10867 @node registered symbol
10868 @subsection @code{@@registeredsymbol@{@}} (@registeredsymbol{})
10869 @findex registeredsymbol
10870 @cindex Registered symbol
10871
10872 Use the @code{@@registeredsymbol@{@}} command to generate the
10873 registered symbol, `@registeredsymbol{}'. Where possible, this is an
10874 @samp{R} inside a circle; in Info, this is @samp{(R)}.
10875
10876
10877 @node euro
10878 @section @code{@@euro}@{@} (@euro{}): Euro Currency Symbol
10879 @findex euro
10880 @cindex Euro symbol
10881
10882 Use the @code{@@euro@{@}} command to generate `@euro{}'. Where
10883 possible, this is the symbol for the Euro currency, invented as part
10884 of the European economic unification. In plain Info, it is the word
10885 @samp{Euro }. A trailing space is included in the text
10886 transliteration since typically no space is desired after the symbol,
10887 so it would be inappropriate to have a space in the source document.
10888
10889 Texinfo cannot magically synthesize support for the Euro symbol where
10890 the underlying system (fonts, software, whatever) does not support
10891 it. Therefore, in many cases it is preferable to use the word
10892 ``Euro''. (In banking circles, the abbreviation for the Euro is EUR.)
10893
10894 @cindex ISO 8859-15
10895 @cindex Latin 9
10896 In order to get the Euro symbol in encoded Info output, for example,
10897 it is necessary to specify @code{@@documentencoding ISO-8859-15}.
10898 (@xref{documentencoding,,@code{@@documentencoding}}.) The Euro symbol
10899 is in ISO 8859-15 (aka Latin@tie{}9), and is @emph{not} in the more
10900 widely-used and supported ISO 8859-1 (Latin@tie{}1).
10901
10902 @pindex feymr10
10903 @cindex Euro font
10904 The Euro symbol does not exist in the standard @TeX{} fonts (which
10905 were designed before the Euro was legislated into existence).
10906 Therefore, @TeX{} uses an additional font, named @code{feymr10} (along
10907 with other variables). It is freely available, of course; you can
10908 download it from @url{http://www.ctan.org/tex-archive/fonts/eurosym},
10909 among other places. The distribution includes installation
10910 instructions.
10911
10912
10913 @node pounds
10914 @section @code{@@pounds}@{@} (@pounds{}): Pounds Sterling
10915 @findex pounds
10916 @cindex Pounds symbol
10917
10918 Use the @code{@@pounds@{@}} command to generate `@pounds{}'. Where
10919 possible, this is the symbol for the currency pounds sterling. In
10920 Info, it is a @samp{#}.
10921
10922
10923 @node textdegree
10924 @section @code{@@textdegree}@{@} (@textdegree{}): Degrees Symbol
10925 @findex textdegree
10926 @cindex Degree symbol
10927
10928 Use the @code{@@textdegree@{@}} command to generate `@textdegree{}'.
10929 Where possible, this is the normal symbol for degrees. In plain text
10930 and Info output, it is an @samp{o}.
10931
10932
10933 @node minus
10934 @section @code{@@minus}@{@} (@minus{}): Inserting a Minus Sign
10935 @findex minus
10936 @cindex Minus sign
10937
10938 @cindex Em dash, compared to minus sign
10939 @cindex Hyphen, compared to minus
10940 Use the @code{@@minus@{@}} command to generate a minus sign. In a
10941 fixed-width font, this is a single hyphen, but in a proportional font,
10942 the symbol is the customary length for a minus sign---a little longer
10943 than a hyphen, shorter than an em-dash:
10944
10945 @display
10946 @samp{@minus{}} is a minus sign generated with @samp{@@minus@{@}},
10947
10948 `-' is a hyphen generated with the character @samp{-},
10949
10950 `---' is an em-dash for text.
10951 @end display
10952
10953 @noindent
10954 In the fixed-width font used by Info, @code{@@minus@{@}} is the same
10955 as a hyphen.
10956
10957 You should not use @code{@@minus@{@}} inside @code{@@code} or
10958 @code{@@example} because the width distinction is not made in the
10959 fixed-width font they use.
10960
10961 When you use @code{@@minus} to specify the mark beginning each entry in
10962 an itemized list, you do not need to type the braces
10963 (@pxref{itemize, , @code{@@itemize}}).
10964
10965
10966 @node geq leq
10967 @section @code{@@geq@{@}} (@geq{}) and @code{@@leq@{@}} (@leq{}): Inserting relations
10968 @findex geq
10969 @findex leq
10970
10971 Use the @code{@@geq@{@}} and @code{@@geq@{@}} commands to generate
10972 greater-than-or-equal and less-than-equal-signs, `@geq{}' and
10973 `@leq{}'. In plain text and Info output, these are the ASCII
10974 sequences @samp{>=} and @samp{<=}. The
10975
10976
10977 @node math
10978 @section @code{@@math}: Inserting Mathematical Expressions
10979 @findex math
10980 @cindex Mathematical expressions
10981 @cindex Formulas, mathematical
10982
10983 You can write a short mathematical expression with the @code{@@math}
10984 command. Write the mathematical expression between braces, like this:
10985
10986 @example
10987 @@math@{(a + b)(a + b) = a^2 + 2ab + b^2@}
10988 @end example
10989
10990 @iftex
10991 @noindent This produces the following in @TeX{}:
10992
10993 @display
10994 @math{(a + b)(a + b) = a^2 + 2ab + b^2}
10995 @end display
10996
10997 @noindent and the following in other formats:
10998 @end iftex
10999 @ifnottex
11000 @noindent This produces the following in Info and HTML:
11001 @end ifnottex
11002
11003 @example
11004 (a + b)(a + b) = a^2 + 2ab + b^2
11005 @end example
11006
11007 The @code{@@math} command has no special effect on the Info and HTML
11008 output. @command{makeinfo} expands any @code{@@}-commands as usual,
11009 but it does not try to produce good mathematical formatting in any
11010 way.
11011
11012 However, as far as the @TeX{} output is concerned, plain @TeX{}
11013 mathematical commands are allowed in @code{@@math}, starting with
11014 @samp{\}, and the plain @TeX{} math characters like @samp{^} and
11015 @samp{_} are also recognized. In essence, @code{@@math} drops you
11016 into plain @TeX{} math mode.
11017
11018 This allows you to conveniently write superscripts and subscripts (as
11019 in the above example), and also to use all the plain @TeX{} math
11020 control sequences for symbols, functions, and so on, and thus get
11021 proper formatting in the @TeX{} output, at least.
11022
11023 It's best to use @samp{\} instead of @samp{@@} for any such
11024 mathematical commands; otherwise, @command{makeinfo} will complain.
11025 On the other hand, input with matching (but unescaped) braces, such as
11026 @samp{k_@{75@}}, is allowed inside @code{@@math}, although
11027 @command{makeinfo} would complain about the bare braces in regular
11028 input.
11029
11030 Here's an example:
11031
11032 @example
11033 @@math@{\sin 2\pi \equiv \cos 3\pi@}
11034 @end example
11035
11036 @iftex
11037 @noindent which looks like this in @TeX{}:
11038 @display
11039 @math{\sin 2\pi \equiv \cos 3\pi}
11040 @end display
11041
11042 @noindent and
11043 @end iftex
11044 @noindent which looks like the input in Info and HTML:
11045 @example
11046 \sin 2\pi \equiv \cos 3\pi
11047 @end example
11048
11049 @findex \ @r{(literal \ in @code{@@math})}
11050 Since @samp{\} is an escape character inside @code{@@math}, you can use
11051 @code{@@\} to get a literal backslash (@code{\\} will work in @TeX{},
11052 but you'd get the literal @samp{\\} in Info). @code{@@\} is not
11053 defined outside of @code{@@math}, since a @samp{\} ordinarily produces a
11054 literal @samp{\}.
11055
11056 @cindex Displayed equations
11057 @cindex Equations, displayed
11058 For displayed equations, you must at present use @TeX{} directly
11059 (@pxref{Raw Formatter Commands}).
11060
11061
11062 @node Click Sequences
11063 @section Click Sequences
11064 @cindex Click sequences
11065 @cindex Sequence of clicks
11066 @cindex GUI click sequence
11067
11068 @findex clicksequence
11069 When documenting graphical interfaces, it is necessary to describe
11070 sequences such as `Click on @samp{File}, then choose @samp{Open}, then
11071 @dots{}'. Texinfo offers commands @code{@@clicksequence} and
11072 @code{click} to represent this, typically used like this:
11073
11074 @example
11075 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
11076 @end example
11077
11078 @noindent
11079 which produces:
11080
11081 @display
11082 @dots{} @clicksequence{File @click{} Open} @dots{}
11083 @end display
11084
11085 @findex click
11086 @findex arrow
11087 The @code{@@click} command produces a simple right arrow (@samp{->} in
11088 Info) by default; this glyph is also available independently via the
11089 command @code{@@arrow@{@}}.
11090
11091 @findex clickstyle
11092 You can change the glyph produced by @code{@@click} with the command
11093 @code{@@clickstyle}, which takes a command name as its single argument
11094 on the rest of the line, much like @code{@@itemize} and friends
11095 (@pxref{itemize,,@code{@@itemize}}). The command should produce a
11096 glyph, and the usual empty braces @samp{@{@}} are omitted. Here's an
11097 example:
11098
11099 @example
11100 @@clickstyle @@result
11101 @dots{} @@clicksequence@{File @@click@{@} Open@} @dots{}
11102 @end example
11103
11104 @noindent
11105 now produces:
11106
11107 @display
11108 @clickstyle @result
11109 @dots{} @clicksequence{File @click{} Open} @dots{}
11110 @end display
11111
11112
11113 @node Glyphs
11114 @section Glyphs for Examples
11115 @cindex Glyphs
11116 @cindex Examples, glyphs for
11117
11118 In Texinfo, code is often illustrated in examples that are delimited
11119 by @code{@@example} and @code{@@end example}, or by @code{@@lisp} and
11120 @code{@@end lisp}. In such examples, you can indicate the results of
11121 evaluation or an expansion using @samp{@result{}} or
11122 @samp{@expansion{}}. Likewise, there are commands to insert glyphs
11123 to indicate
11124 printed output, error messages, equivalence of expressions, and the
11125 location of point.
11126
11127 The glyph-insertion commands do not need to be used within an example, but
11128 most often they are. Every glyph-insertion command is followed by a pair of
11129 left- and right-hand braces.@refill
11130
11131 @menu
11132 * Glyphs Summary::
11133 * result:: How to show the result of expression.
11134 * expansion:: How to indicate an expansion.
11135 * Print Glyph:: How to indicate printed output.
11136 * Error Glyph:: How to indicate an error message.
11137 * Equivalence:: How to indicate equivalence.
11138 * Point Glyph:: How to indicate the location of point.
11139 @end menu
11140
11141
11142 @node Glyphs Summary
11143 @subsection Glyphs Summary
11144
11145 Here are the different glyph commands:@refill
11146
11147 @table @asis
11148 @item @result{}
11149 @code{@@result@{@}} points to the result of an expression.@refill
11150
11151 @item @expansion{}
11152 @code{@@expansion@{@}} shows the results of a macro expansion.@refill
11153
11154 @item @print{}
11155 @code{@@print@{@}} indicates printed output.@refill
11156
11157 @item @error{}
11158 @code{@@error@{@}} indicates that the following text is an error
11159 message.@refill
11160
11161 @item @equiv{}
11162 @code{@@equiv@{@}} indicates the exact equivalence of two forms.@refill
11163
11164 @item @point{}
11165 @code{@@point@{@}} shows the location of point.@refill
11166 @end table
11167
11168 @menu
11169 * result::
11170 * expansion::
11171 * Print Glyph::
11172 * Error Glyph::
11173 * Equivalence::
11174 * Point Glyph::
11175 @end menu
11176
11177
11178 @node result
11179 @subsection @code{@@result@{@}} (@result{}): Indicating Evaluation
11180 @cindex Result of an expression
11181 @cindex Indicating evaluation
11182 @cindex Evaluation glyph
11183 @cindex Value of an expression, indicating
11184 @findex result
11185
11186 Use the @code{@@result@{@}} command to indicate the result of
11187 evaluating an expression.@refill
11188
11189 @iftex
11190 The @code{@@result@{@}} command is displayed as @samp{@result{}} in
11191 the printed output and as @samp{=>} in other formats.
11192 @end iftex
11193 @ifnottex
11194 The @code{@@result@{@}} command is displayed as @samp{@result{}} in
11195 Info and HTML and as a true double stemmed arrow in the printed output.
11196 @end ifnottex
11197
11198 Thus, the following,
11199
11200 @lisp
11201 (cdr '(1 2 3))
11202 @result{} (2 3)
11203 @end lisp
11204
11205 @noindent
11206 may be read as ``@code{(cdr '(1 2 3))} evaluates to @code{(2 3)}''.
11207
11208
11209 @node expansion
11210 @subsection @code{@@expansion@{@}} (@expansion{}): Indicating an Expansion
11211 @cindex Expansion, indicating
11212 @cindex Macro expansion, indicating
11213 @findex expansion
11214
11215 When an expression is a macro call, it expands into a new expression.
11216 You can indicate the result of the expansion with the
11217 @code{@@expansion@{@}} command.@refill
11218
11219 @iftex
11220 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
11221 in the printed output and as @samp{==>} in other formats.
11222 @end iftex
11223 @ifnottex
11224 The @code{@@expansion@{@}} command is displayed as @samp{@expansion{}}
11225 in Info and HTML, and as a long arrow with a flat base in the printed
11226 output.
11227 @end ifnottex
11228
11229 @need 700
11230 For example, the following
11231
11232 @example
11233 @group
11234 @@lisp
11235 (third '(a b c))
11236 @@expansion@{@} (car (cdr (cdr '(a b c))))
11237 @@result@{@} c
11238 @@end lisp
11239 @end group
11240 @end example
11241
11242 @noindent
11243 produces
11244
11245 @lisp
11246 @group
11247 (third '(a b c))
11248 @expansion{} (car (cdr (cdr '(a b c))))
11249 @result{} c
11250 @end group
11251 @end lisp
11252
11253 @noindent
11254 which may be read as:
11255
11256 @quotation
11257 @code{(third '(a b c))} expands to @code{(car (cdr (cdr '(a b c))))};
11258 the result of evaluating the expression is @code{c}.
11259 @end quotation
11260
11261 @noindent
11262 Often, as in this case, an example looks better if the
11263 @code{@@expansion@{@}} and @code{@@result@{@}} commands are indented.
11264
11265
11266 @node Print Glyph
11267 @subsection @code{@@print@{@}} (@print{}): Indicating Printed Output
11268 @cindex Printed output, indicating
11269 @findex print
11270
11271 Sometimes an expression will print output during its execution. You
11272 can indicate the printed output with the @code{@@print@{@}} command.@refill
11273
11274 @iftex
11275 The @code{@@print@{@}} command is displayed as @samp{-|} in Info and
11276 HTML and as @samp{@print{}} in the printed output.
11277 @end iftex
11278 @ifnottex
11279 The @code{@@print@{@}} command is displayed as @samp{@print{}} in Info
11280 and HTML and (similarly) as a horizontal dash butting against a
11281 vertical bar in the printed output.
11282 @end ifnottex
11283
11284 In the following example, the printed text is indicated with
11285 @samp{@print{}}, and the value of the expression follows on the
11286 last line.
11287
11288 @lisp
11289 @group
11290 (progn (print 'foo) (print 'bar))
11291 @print{} foo
11292 @print{} bar
11293 @result{} bar
11294 @end group
11295 @end lisp
11296
11297 @noindent
11298 In a Texinfo source file, this example is written as follows:
11299
11300 @lisp
11301 @group
11302 @@lisp
11303 (progn (print 'foo) (print 'bar))
11304 @@print@{@} foo
11305 @@print@{@} bar
11306 @@result@{@} bar
11307 @@end lisp
11308 @end group
11309 @end lisp
11310
11311
11312 @node Error Glyph
11313 @subsection @code{@@error@{@}} (@error{}): Indicating an Error Message
11314 @cindex Error message, indicating
11315 @findex error
11316
11317 A piece of code may cause an error when you evaluate it. You can
11318 designate the error message with the @code{@@error@{@}} command.@refill
11319
11320 @iftex
11321 The @code{@@error@{@}} command is displayed as @samp{error-->} in Info
11322 and HTML and as @samp{@error{}} in the printed output.
11323 @end iftex
11324 @ifnottex
11325 The @code{@@error@{@}} command is displayed as @samp{@error{}} in Info
11326 and HTML and as the word `error' in a box in the printed output.
11327 @end ifnottex
11328
11329 @need 700
11330 Thus,
11331
11332 @example
11333 @@lisp
11334 (+ 23 'x)
11335 @@error@{@} Wrong type argument: integer-or-marker-p, x
11336 @@end lisp
11337 @end example
11338
11339 @noindent
11340 produces
11341
11342 @lisp
11343 (+ 23 'x)
11344 @error{} Wrong type argument: integer-or-marker-p, x
11345 @end lisp
11346
11347 @noindent
11348 This indicates that the following error message is printed
11349 when you evaluate the expression:
11350
11351 @lisp
11352 Wrong type argument: integer-or-marker-p, x
11353 @end lisp
11354
11355 @samp{@error{}} itself is not part of the error message.
11356
11357
11358 @node Equivalence
11359 @subsection @code{@@equiv@{@}} (@equiv{}): Indicating Equivalence
11360 @cindex Equivalence, indicating
11361 @findex equiv
11362
11363 Sometimes two expressions produce identical results. You can indicate the
11364 exact equivalence of two forms with the @code{@@equiv@{@}} command.@refill
11365
11366 @iftex
11367 The @code{@@equiv@{@}} command is displayed as @samp{==} in Info and
11368 HTML and as @samp{@equiv{}} in the printed output.
11369 @end iftex
11370 @ifnottex
11371 The @code{@@equiv@{@}} command is displayed as @samp{@equiv{}} in Info
11372 and HTML and as a standard mathematical equivalence sign (three
11373 parallel horizontal lines) in the printed output.
11374 @end ifnottex
11375
11376 Thus,
11377
11378 @example
11379 @@lisp
11380 (make-sparse-keymap) @@equiv@{@} (list 'keymap)
11381 @@end lisp
11382 @end example
11383
11384 @noindent
11385 produces
11386
11387 @lisp
11388 (make-sparse-keymap) @equiv{} (list 'keymap)
11389 @end lisp
11390
11391 @noindent
11392 This indicates that evaluating @code{(make-sparse-keymap)} produces
11393 identical results to evaluating @code{(list 'keymap)}.
11394
11395
11396 @node Point Glyph
11397 @subsection @code{@@point@{@}} (@point{}): Indicating Point in a Buffer
11398 @cindex Point, indicating in a buffer
11399 @findex point
11400
11401 Sometimes you need to show an example of text in an XEmacs buffer. In
11402 such examples, the convention is to include the entire contents of the
11403 buffer in question between two lines of dashes containing the buffer
11404 name.@refill
11405
11406 You can use the @samp{@@point@{@}} command to show the location of point
11407 in the text in the buffer. (The symbol for point, of course, is not
11408 part of the text in the buffer; it indicates the place @emph{between}
11409 two characters where point is located.)@refill
11410
11411 @iftex
11412 The @code{@@point@{@}} command is displayed as @samp{-!-} in Info and
11413 HTML and as @samp{@point{}} in the printed output.
11414 @end iftex
11415 @ifnottex
11416 The @code{@@point@{@}} command is displayed as @samp{@point{}} in Info
11417 and HTML and as a small five pointed star in the printed
11418 output.
11419 @end ifnottex
11420
11421 The following example shows the contents of buffer @file{foo} before
11422 and after evaluating a Lisp command to insert the word @code{changed}.@refill
11423
11424 @example
11425 @group
11426 ---------- Buffer: foo ----------
11427 This is the @point{}contents of foo.
11428 ---------- Buffer: foo ----------
11429
11430 @end group
11431 @end example
11432
11433 @example
11434 @group
11435 (insert "changed ")
11436 @result{} nil
11437 ---------- Buffer: foo ----------
11438 This is the changed @point{}contents of foo.
11439 ---------- Buffer: foo ----------
11440
11441 @end group
11442 @end example
11443
11444 In a Texinfo source file, the example is written like this:@refill
11445
11446 @example
11447 @@example
11448 ---------- Buffer: foo ----------
11449 This is the @@point@{@}contents of foo.
11450 ---------- Buffer: foo ----------
11451
11452 (insert "changed ")
11453 @@result@{@} nil
11454 ---------- Buffer: foo ----------
11455 This is the changed @@point@{@}contents of foo.
11456 ---------- Buffer: foo ----------
11457 @@end example
11458 @end example
11459
11460
11461 @node Breaks
11462 @chapter Forcing and Preventing Breaks
11463 @cindex Forcing line and page breaks
11464 @cindex Making line and page breaks
11465 @cindex Preventing line and page breaks
11466
11467 @cindex Line breaks
11468 Usually, a Texinfo file is processed both by @TeX{} and by one of the
11469 Info formatting commands. Line, paragraph, or page breaks sometimes
11470 occur in the `wrong' place in one or other form of output. You must
11471 ensure that text looks right both in the printed manual and in the
11472 Info file.
11473
11474 @cindex White space, excessive
11475 @cindex Page breaks
11476 For example, in a printed manual, page breaks may occur awkwardly in
11477 the middle of an example; to prevent this, you can hold text together
11478 using a grouping command that keeps the text from being split across
11479 two pages. Conversely, you may want to force a page break where none
11480 would occur normally. Fortunately, problems like these do not often
11481 arise. When they do, use the break, break prevention, or pagination
11482 commands.
11483
11484 @menu
11485 * Break Commands:: Summary of break-related commands.
11486 * Line Breaks:: Forcing line breaks.
11487 * - and hyphenation:: Helping @TeX{} with hyphenation points.
11488 * allowcodebreaks:: Controlling line breaks within @@code text.
11489 * w:: Preventing unwanted line breaks in text.
11490 * tie:: Inserting an unbreakable but varying space.
11491 * sp:: Inserting blank lines.
11492 * page:: Forcing the start of a new page.
11493 * group:: Preventing unwanted page breaks.
11494 * need:: Another way to prevent unwanted page breaks.
11495 @end menu
11496
11497
11498 @node Break Commands
11499 @section Break Commands
11500
11501 The break commands create or allow line and paragraph breaks:
11502
11503 @table @code
11504 @item @@*
11505 Force a line break.
11506
11507 @item @@sp @var{n}
11508 Skip @var{n} blank lines.
11509
11510 @item @@-
11511 Insert a discretionary hyphen.
11512
11513 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
11514 Define hyphen points in @var{hy-phen-a-ted words}.
11515 @end table
11516
11517 These commands hold text together on a single line:
11518
11519 @table @code
11520 @item @@w@{@var{text}@}
11521 Prevent @var{text} from being split and hyphenated across two lines.
11522 @item @@tie@{@}
11523 Insert a normal interword space at which a line break may not occur.
11524 @end table
11525 @iftex
11526 @sp 1
11527 @end iftex
11528
11529 The pagination commands apply only to printed output, since Info
11530 files do not have pages.
11531
11532 @table @code
11533 @item @@page
11534 Start a new page in the printed manual.
11535
11536 @item @@group
11537 Hold text together that must appear on one printed page.
11538
11539 @item @@need @var{mils}
11540 Start a new printed page if not enough space on this one.
11541 @end table
11542
11543
11544 @node Line Breaks
11545 @section @code{@@*} and @code{@@/}: Generate and Allow Line Breaks
11546 @findex * @r{(force line break)}
11547 @findex / @r{(allow line break)}
11548 @cindex Line breaks
11549 @cindex Breaks in a line
11550 @cindex Force line break
11551 @cindex Allow line break
11552
11553 The @code{@@*} command forces a line break in both the printed manual and
11554 in Info. The @code{@@/} command allows a line break (printed manual only).
11555
11556 Here is an example with @code{@@*}:
11557
11558 @example
11559 This line @@* is broken @@*in two places.
11560 @end example
11561
11562 @noindent produces
11563
11564 @example
11565 @group
11566 This line
11567 is broken
11568 in two places.
11569 @end group
11570 @end example
11571
11572 The @code{@@/} command can be useful within a url
11573 (@pxref{uref,,@code{@@uref}}), which tend to be long and are otherwise
11574 unbreakable. For example:
11575
11576 @example
11577 The official Texinfo home page is on the GNU web site:
11578 @@uref@{http://www.gnu.org/@@/software/@@/gnu/@@/texinfo@}.
11579 @end example
11580
11581 @noindent produces
11582
11583 @display
11584 The official Texinfo home page is on the GNU web site:
11585 @uref{http://www.gnu.org/@/software/@/gnu/@/texinfo}.
11586 @end display
11587
11588 @noindent Without the @code{@@/} commands, @TeX{} would have nowhere to
11589 break the line. @code{@@/} has no effect in the online output.
11590
11591
11592 @node - and hyphenation
11593 @section @code{@@-} and @code{@@hyphenation}: Helping @TeX{} Hyphenate
11594
11595 @findex - @r{(discretionary hyphen)}
11596 @findex hyphenation
11597 @cindex Hyphenation, helping @TeX{} do
11598 @cindex Fine-tuning, and hyphenation
11599
11600 Although @TeX{}'s hyphenation algorithm is generally pretty good, it
11601 does miss useful hyphenation points from time to time. (Or, far more
11602 rarely, insert an incorrect hyphenation.) So, for documents with an
11603 unusual vocabulary or when fine-tuning for a printed edition, you may
11604 wish to help @TeX{} out. Texinfo supports two commands for this:
11605
11606 @table @code
11607 @item @@-
11608 Insert a discretionary hyphen, i.e., a place where @TeX{} can (but does
11609 not have to) hyphenate. This is especially useful when you notice an
11610 overfull hbox is due to @TeX{} missing a hyphenation (@pxref{Overfull
11611 hboxes}). @TeX{} will not insert any hyphenation points itself into a
11612 word containing @code{@@-}.
11613
11614 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
11615 Tell @TeX{} how to hyphenate @var{hy-phen-a-ted words}. As shown, you
11616 put a @samp{-} at each hyphenation point. For example:
11617 @example
11618 @@hyphenation@{man-u-script man-u-scripts@}
11619 @end example
11620 @noindent @TeX{} only uses the specified hyphenation points when the
11621 words match exactly, so give all necessary variants, such as plurals.
11622 @end table
11623
11624 Info, HTML, and other non-@TeX{} output is not hyphenated, so none of
11625 these commands have any effect there.
11626
11627
11628 @node allowcodebreaks
11629 @section @code{@@allowcodebreaks}: Control Line Breaks in @code{@@code}
11630
11631 @findex allowcodebreaks
11632 @cindex Breaks, within @code{@@code}
11633 @cindex -, breakpoint within @code{@@code}
11634 @cindex Hyphen, breakpoint within @code{@@code}
11635 @cindex Dash, breakpoint within @code{@@code}
11636 @cindex _, breakpoint within @code{@@code}
11637 @cindex Underscore, breakpoint within @code{@@code}
11638
11639 Ordinarily, @TeX{} will consider breaking lines at @samp{-} and
11640 @samp{_} characters within @code{@@code} and related commands
11641 (@pxref{code,,@code{@@code}}), more or less as if they were ``empty''
11642 hyphenation points.
11643
11644 This is necessary as many manuals, especially for Lisp-family
11645 languages, must document very long identifiers. On the other hand,
11646 other manuals don't have this problems, and you may not wish to allow
11647 a line break at the underscore in, for example, @code{SIZE_MAX}, or
11648 even worse, after any of the four underscores in @code{__typeof__}.
11649
11650 So Texinfo provides this command:
11651
11652 @example
11653 @@allowcodebreaks false
11654 @end example
11655
11656 @noindent to prevent @TeX{} from breaking at @samp{-} or @samp{_} within
11657 @code{@@code}. You can go back to allowing such breaks with
11658 @code{@@allowcodebreaks true}. Write these commands on lines by
11659 themselves.
11660
11661 These commands can be given anywhere in the document. For example,
11662 you may have just one problematic paragraph where you need to turn off
11663 the breaks, but want them in general, or vice versa.
11664
11665 This command has no effect in Info, HTML, and other non-@TeX{} output.
11666
11667
11668 @node w
11669 @section @code{@@w}@{@var{text}@}: Prevent Line Breaks
11670 @findex w @r{(prevent line break)}
11671 @cindex Line breaks, preventing
11672
11673 @code{@@w@{@var{text}@}} outputs @var{text} and prohibits line breaks
11674 within @var{text}, for both @TeX{} and @command{makeinfo}.
11675
11676 @cindex Non-breakable space, fixed
11677 @cindex Unbreakable space, fixed
11678 Thus, you can use @code{@@w} to produce a non-breakable space, fixed at
11679 the width of a normal interword space:
11680
11681 @example
11682 @@w@{ @} @@w@{ @} @@w@{ @} indentation.
11683 @end example
11684
11685 @noindent produces:
11686
11687 @display
11688 @w{ } @w{ } @w{ } indentation.
11689 @end display
11690
11691 The space from @code{@@w@{@w{ }@}}, as well as being non-breakable,
11692 also will not stretch or shrink. Sometimes that is what you want, for
11693 instance if you're doing manual indenting. However, usually you want
11694 a normal interword space that does stretch and shrink (in the printed
11695 output); see the @code{@@tie} command in the next section.
11696
11697 @cindex Hyphenation, preventing
11698 You can also use the @code{@@w} command to prevent @TeX{} from
11699 automatically hyphenating a long name or phrase that happens to fall
11700 near the end of a line. @command{makeinfo} does not ever hyphenate
11701 words.
11702
11703 @cindex Keyword expansion, preventing
11704 @cindex Version control keywords, preventing expansion of
11705 @cindex $Id expansion, preventing
11706 You can also use @code{@@w} to avoid unwanted keyword expansion in
11707 source control systems. For example, to literally write @t{@w{$}Id$}
11708 in your document, use @code{@@w@{$@}Id$}.
11709
11710
11711 @node tie
11712 @section @code{@@tie@{@}}: Inserting an Unbreakable Space
11713 @findex tie @r{(unbreakable interword space)}
11714 @cindex Tied space
11715 @cindex Non-breakable space, variable
11716 @cindex Unbreakable space, variable
11717
11718 The @code{@@tie@{@}} command produces a normal interword space at which
11719 a line break may not occur. Always write it with following (empty)
11720 braces, as usual for commands used within a paragraph. Here's an
11721 example:
11722
11723 @example
11724 @@TeX@{@} was written by Donald E.@@tie@{@}Knuth.
11725 @end example
11726
11727 @noindent produces:
11728
11729 @display
11730 @TeX{} was written by Donald E.@tie{}Knuth.
11731 @end display
11732
11733 There are two important differences between @code{@@tie@{@}} and
11734 @code{@@w@{@w{ }@}}:
11735
11736 @itemize
11737 @item
11738 The space produced by @code{@@tie@{@}} will stretch and shrink slightly
11739 along with the normal interword spaces in the paragraph; the space
11740 produced by @code{@@w@{@w{ }@}} will not vary.
11741
11742 @item
11743 @code{@@tie@{@}} allows hyphenation of the surrounding words, while
11744 @code{@@w@{@w{ }@}} inhibits hyphenation of those words (for @TeX{}nical
11745 reasons, namely that it produces an @samp{\hbox}).
11746
11747 @end itemize
11748
11749
11750 @node sp
11751 @section @code{@@sp} @var{n}: Insert Blank Lines
11752 @findex sp @r{(line spacing)}
11753 @cindex Space, inserting vertical
11754 @cindex Blank lines
11755 @cindex Line spacing
11756
11757 A line beginning with and containing only @code{@@sp @var{n}}
11758 generates @var{n} blank lines of space in both the printed manual and
11759 the Info file. @code{@@sp} also forces a paragraph break. For
11760 example,
11761
11762 @example
11763 @@sp 2
11764 @end example
11765
11766 @noindent
11767 generates two blank lines.
11768
11769 The @code{@@sp} command is most often used in the title page.@refill
11770
11771 @ignore
11772 @c node br, page, sp, Breaks
11773 @comment node-name, next, previous, up
11774 @c section @code{@@br}: Generate Paragraph Breaks
11775 @findex br @r{(paragraph breaks)}
11776 @cindex Paragraph breaks
11777 @cindex Breaks in a paragraph
11778
11779 The @code{@@br} command forces a paragraph break. It inserts a blank
11780 line. You can use the command within or at the end of a line. If
11781 used within a line, the @code{@@br@{@}} command must be followed by
11782 left and right braces (as shown here) to mark the end of the
11783 command.@refill
11784
11785 @need 700
11786 For example,
11787
11788 @example
11789 @group
11790 This line @@br@{@}contains and is ended by paragraph breaks@@br
11791 and is followed by another line.
11792 @end group
11793 @end example
11794
11795 @noindent
11796 produces
11797
11798 @example
11799 @group
11800 This line
11801
11802 contains and is ended by paragraph breaks
11803
11804 and is followed by another line.
11805 @end group
11806 @end example
11807
11808 The @code{@@br} command is seldom used.
11809 @end ignore
11810
11811
11812 @node page
11813 @section @code{@@page}: Start a New Page
11814 @cindex Page breaks
11815 @findex page
11816
11817 A line containing only @code{@@page} starts a new page in a printed
11818 manual. The command has no effect on Info files since they are not
11819 paginated. An @code{@@page} command is often used in the @code{@@titlepage}
11820 section of a Texinfo file to start the copyright page.
11821
11822
11823 @node group
11824 @comment node-name, next, previous, up
11825 @section @code{@@group}: Prevent Page Breaks
11826 @cindex Group (hold text together vertically)
11827 @cindex Holding text together vertically
11828 @cindex Vertically holding text together
11829 @findex group
11830
11831 The @code{@@group} command (on a line by itself) is used inside an
11832 @code{@@example} or similar construct to begin an unsplittable vertical
11833 group, which will appear entirely on one page in the printed output.
11834 The group is terminated by a line containing only @code{@@end group}.
11835 These two lines produce no output of their own, and in the Info file
11836 output they have no effect at all.@refill
11837
11838 @c Once said that these environments
11839 @c turn off vertical spacing between ``paragraphs''.
11840 @c Also, quotation used to work, but doesn't in texinfo-2.72
11841 Although @code{@@group} would make sense conceptually in a wide
11842 variety of contexts, its current implementation works reliably only
11843 within @code{@@example} and variants, and within @code{@@display},
11844 @code{@@format}, @code{@@flushleft} and @code{@@flushright}.
11845 @xref{Quotations and Examples}. (What all these commands have in
11846 common is that each line of input produces a line of output.) In
11847 other contexts, @code{@@group} can cause anomalous vertical
11848 spacing.@refill
11849
11850 @need 750
11851 This formatting requirement means that you should write:
11852
11853 @example
11854 @group
11855 @@example
11856 @@group
11857 @dots{}
11858 @@end group
11859 @@end example
11860 @end group
11861 @end example
11862
11863 @noindent
11864 with the @code{@@group} and @code{@@end group} commands inside the
11865 @code{@@example} and @code{@@end example} commands.
11866
11867 The @code{@@group} command is most often used to hold an example
11868 together on one page. In this Texinfo manual, more than 100 examples
11869 contain text that is enclosed between @code{@@group} and @code{@@end
11870 group}.
11871
11872 If you forget to end a group, you may get strange and unfathomable
11873 error messages when you run @TeX{}. This is because @TeX{} keeps
11874 trying to put the rest of the Texinfo file onto the one page and does
11875 not start to generate error messages until it has processed
11876 considerable text. It is a good rule of thumb to look for a missing
11877 @code{@@end group} if you get incomprehensible error messages in
11878 @TeX{}.@refill
11879
11880 @node need
11881 @comment node-name, next, previous, up
11882 @section @code{@@need @var{mils}}: Prevent Page Breaks
11883 @cindex Need space at page bottom
11884 @findex need
11885
11886 A line containing only @code{@@need @var{n}} starts
11887 a new page in a printed manual if fewer than @var{n} mils (thousandths
11888 of an inch) remain on the current page. Do not use
11889 braces around the argument @var{n}. The @code{@@need} command has no
11890 effect on Info files since they are not paginated.@refill
11891
11892 @need 800
11893 This paragraph is preceded by an @code{@@need} command that tells
11894 @TeX{} to start a new page if fewer than 800 mils (eight-tenths
11895 inch) remain on the page. It looks like this:@refill
11896
11897 @example
11898 @group
11899 @@need 800
11900 This paragraph is preceded by @dots{}
11901 @end group
11902 @end example
11903
11904 The @code{@@need} command is useful for preventing orphans (single
11905 lines at the bottoms of printed pages).@refill
11906
11907
11908 @node Definition Commands
11909 @chapter Definition Commands
11910 @cindex Definition commands
11911
11912 The @code{@@deffn} command and the other @dfn{definition commands}
11913 enable you to describe functions, variables, macros, commands, user
11914 options, special forms and other such artifacts in a uniform
11915 format.@refill
11916
11917 In the Info file, a definition causes the entity
11918 category---`Function', `Variable', or whatever---to appear at the
11919 beginning of the first line of the definition, followed by the
11920 entity's name and arguments. In the printed manual, the command
11921 causes @TeX{} to print the entity's name and its arguments on the left
11922 margin and print the category next to the right margin. In both
11923 output formats, the body of the definition is indented. Also, the
11924 name of the entity is entered into the appropriate index:
11925 @code{@@deffn} enters the name into the index of functions,
11926 @code{@@defvr} enters it into the index of variables, and so
11927 on (@pxref{Predefined Indices}).
11928
11929 A manual need not and should not contain more than one definition for
11930 a given name. An appendix containing a summary should use
11931 @code{@@table} rather than the definition commands.@refill
11932
11933 @menu
11934 * Def Cmd Template:: Writing descriptions using definition commands.
11935 * Def Cmd Continuation Lines:: Continuing the heading over source lines.
11936 * Optional Arguments:: Handling optional and repeated arguments.
11937 * deffnx:: Group two or more `first' lines.
11938 * Def Cmds in Detail:: Reference for all the definition commands.
11939 * Def Cmd Conventions:: Conventions for writing definitions.
11940 * Sample Function Definition:: An example.
11941 @end menu
11942
11943
11944 @node Def Cmd Template
11945 @section The Template for a Definition
11946 @cindex Definition template
11947 @cindex Template for a definition
11948
11949 The @code{@@deffn} command is used for definitions of entities that
11950 resemble functions. To write a definition using the @code{@@deffn}
11951 command, write the @code{@@deffn} command at the beginning of a line
11952 and follow it on the same line by the category of the entity, the name
11953 of the entity itself, and its arguments (if any). Then write the body
11954 of the definition on succeeding lines. (You may embed examples in the
11955 body.) Finally, end the definition with an @code{@@end deffn} command
11956 written on a line of its own.
11957
11958 The other definition commands follow the same format: a line with the
11959 @code{@@def@dots{}} command and whatever arguments are appropriate for
11960 that command; the body of the definition; and a corresponding
11961 @code{@@end} line.
11962
11963 The template for a definition looks like this:
11964
11965 @example
11966 @group
11967 @@deffn @var{category} @var{name} @var{arguments}@dots{}
11968 @var{body-of-definition}
11969 @@end deffn
11970 @end group
11971 @end example
11972
11973 @need 700
11974 @noindent
11975 For example,
11976
11977 @example
11978 @group
11979 @@deffn Command forward-word count
11980 This command moves point forward @@var@{count@} words
11981 (or backward if @@var@{count@} is negative). @dots{}
11982 @@end deffn
11983 @end group
11984 @end example
11985
11986 @noindent
11987 produces
11988
11989 @quotation
11990 @deffn Command forward-word count
11991 This command moves point forward @var{count} words
11992 (or backward if @var{count} is negative). @dots{}
11993 @end deffn
11994 @end quotation
11995
11996 Capitalize the category name like a title. If the name of the
11997 category contains spaces, as in the phrase `Interactive Command',
11998 enclose it in braces. For example:
11999
12000 @example
12001 @group
12002 @@deffn @{Interactive Command@} isearch-forward
12003 @dots{}
12004 @@end deffn
12005 @end group
12006 @end example
12007
12008 @noindent
12009 Otherwise, the second word will be mistaken for the name of the
12010 entity. As a general rule, when any of the arguments in the heading
12011 line @emph{except} the last one are more than one word, you need to
12012 enclose them in braces. This may also be necessary if the text
12013 contains commands, for example, @samp{@{declaraci@@'on@}} if you are
12014 writing in Spanish.
12015
12016 Some of the definition commands are more general than others. The
12017 @code{@@deffn} command, for example, is the general definition command
12018 for functions and the like---for entities that may take arguments.
12019 When you use this command, you specify the category to which the
12020 entity belongs. Three predefined, specialized variations
12021 (@code{@@defun}, @code{@@defmac}, and @code{@@defspec}) specify the
12022 category for you: ``Function'', ``Macro'', and ``Special Form''
12023 respectively. (In Lisp, a special form is an entity much like a
12024 function.) Similarly, the general @code{@@defvr} command is
12025 accompanied by several specialized variations for describing
12026 particular kinds of variables.
12027
12028 @xref{Sample Function Definition}, for a detailed example of a
12029 function definition, including the use of @code{@@example} inside the
12030 definition.
12031
12032 @cindex Macros in definition commands
12033 Unfortunately, due to implementation difficulties, macros are not expanded
12034 in @code{@@deffn} and all the other definition commands.
12035
12036
12037 @node Def Cmd Continuation Lines
12038 @section Definition Command Continuation Lines
12039 @cindex Continuation lines in definition commands
12040 @cindex Definition command headings, continuing
12041 @cindex @samp{@@} as continuation in definition commands
12042
12043 The heading line of a definition command can get very long.
12044 Therefore, Texinfo has a special syntax allowing them to be continued
12045 over multiple lines of the source file: a lone @samp{@@} at the end of
12046 each line to be continued. Here's an example:
12047
12048 @example
12049 @@defun fn-name @@
12050 arg1 arg2 arg3
12051 This is the basic continued defun.
12052 @@end defun
12053 @end example
12054
12055 @noindent produces:
12056
12057 @defun fn-name @
12058 arg1 arg2 arg3
12059 This is the basic continued defun.
12060 @end defun
12061
12062 @noindent
12063 As you can see, the continued lines are combined, as if they had been
12064 typed on one source line.
12065
12066 Although this example only shows a one-line continuation,
12067 continuations may extend over any number of lines; simply put an
12068 @code{@@} at the end of each line to be continued.
12069
12070 The @code{@@} character does not have to be the last character on the
12071 physical line: whitespace is allowed (and ignored) afterwards.
12072
12073 @cindex Whitespace, collapsed around continuations
12074 @cindex Collapsing whitespace around continuations
12075 In general, any number of spaces or tabs around the @code{@@}
12076 continuation character, both on the line with the @code{@@} and on the
12077 continued line, are collapsed into a single space. There is one
12078 exception: the Texinfo processors will not fully collapse whitespace
12079 around a continuation inside braces. For example:
12080
12081 @example
12082 @@deffn @{Category @@
12083 Name@} @dots{}
12084 @end example
12085
12086 @noindent The output (not shown) has excess space between `Category'
12087 and `Name'. In this case, simply elide any unwanted whitespace in
12088 your input, or put the continuation @code{@@} outside braces.
12089
12090 @code{@@} does not (currently) function as a continuation character in
12091 @emph{any} other context. Ordinarily, @samp{@@} followed by a
12092 whitespace character (space, tab, newline) produces a normal interword
12093 space (@pxref{Multiple Spaces}).
12094
12095
12096 @node Optional Arguments
12097 @section Optional and Repeated Arguments
12098 @cindex Optional and repeated arguments
12099 @cindex Repeated and optional arguments
12100 @cindex Arguments, repeated and optional
12101 @cindex Syntax, optional & repeated arguments
12102 @cindex Meta-syntactic chars for arguments
12103
12104 Some entities take optional or repeated arguments, which may be
12105 specified by a distinctive glyph that uses square brackets and
12106 ellipses. For @w{example}, a special form often breaks its argument list
12107 into separate arguments in more complicated ways than a
12108 straightforward function.
12109
12110 @c This is consistent with XEmacs Lisp Reference manual
12111 An argument enclosed within square brackets is optional.
12112 Thus, [@var{optional-arg}] means that @var{optional-arg} is optional.
12113 An argument followed by an ellipsis is optional
12114 and may be repeated more than once.
12115 @c This is consistent with XEmacs Lisp Reference manual
12116 Thus, @var{repeated-args}@samp{@dots{}} stands for zero or more
12117 arguments. Parentheses are used when several arguments are grouped
12118 into additional levels of list structure in Lisp.
12119
12120 Here is the @code{@@defspec} line of an example of an imaginary
12121 special form:
12122
12123 @quotation
12124 @defspec foobar (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{}
12125 @end defspec
12126 @tex
12127 \vskip \parskip
12128 @end tex
12129 @end quotation
12130
12131 @noindent
12132 In this example, the arguments @var{from} and @var{to} are optional,
12133 but must both be present or both absent. If they are present,
12134 @var{inc} may optionally be specified as well. These arguments are
12135 grouped with the argument @var{var} into a list, to distinguish them
12136 from @var{body}, which includes all remaining elements of the
12137 form.@refill
12138
12139 In a Texinfo source file, this @code{@@defspec} line is written like
12140 this (except it would not be split over two lines, as it is in this
12141 example).@refill
12142
12143 @example
12144 @group
12145 @@defspec foobar (@@var@{var@} [@@var@{from@} @@var@{to@}
12146 [@@var@{inc@}]]) @@var@{body@}@@dots@{@}
12147 @end group
12148 @end example
12149
12150 @noindent
12151 The function is listed in the Command and Variable Index under
12152 @samp{foobar}.@refill
12153
12154
12155 @node deffnx
12156 @section Two or More `First' Lines
12157 @cindex Two `First' Lines for @code{@@deffn}
12158 @cindex Grouping two definitions together
12159 @cindex Definitions grouped together
12160 @findex deffnx
12161
12162 To create two or more `first' or header lines for a definition, follow
12163 the first @code{@@deffn} line by a line beginning with @code{@@deffnx}.
12164 The @code{@@deffnx} command works exactly like @code{@@deffn}
12165 except that it does not generate extra vertical white space between it
12166 and the preceding line.@refill
12167
12168 @need 1000
12169 For example,
12170
12171 @example
12172 @group
12173 @@deffn @{Interactive Command@} isearch-forward
12174 @@deffnx @{Interactive Command@} isearch-backward
12175 These two search commands are similar except @dots{}
12176 @@end deffn
12177 @end group
12178 @end example
12179
12180 @noindent
12181 produces
12182
12183 @deffn {Interactive Command} isearch-forward
12184 @deffnx {Interactive Command} isearch-backward
12185 These two search commands are similar except @dots{}
12186 @end deffn
12187
12188 Each definition command has an `x' form: @code{@@defunx},
12189 @code{@@defvrx}, @code{@@deftypefunx}, etc.
12190
12191 The `x' forms work similarly to @code{@@itemx} (@pxref{itemx}).
12192
12193
12194 @node Def Cmds in Detail
12195 @section The Definition Commands
12196
12197 Texinfo provides more than a dozen definition commands, all of which
12198 are described in this section.@refill
12199
12200 The definition commands automatically enter the name of the entity in
12201 the appropriate index: for example, @code{@@deffn}, @code{@@defun},
12202 and @code{@@defmac} enter function names in the index of functions;
12203 @code{@@defvr} and @code{@@defvar} enter variable names in the index
12204 of variables.@refill
12205
12206 Although the examples that follow mostly illustrate Lisp, the commands
12207 can be used for other programming languages.@refill
12208
12209 @menu
12210 * Functions Commands:: Commands for functions and similar entities.
12211 * Variables Commands:: Commands for variables and similar entities.
12212 * Typed Functions:: Commands for functions in typed languages.
12213 * Typed Variables:: Commands for variables in typed languages.
12214 * Data Types:: The definition command for data types.
12215 * Abstract Objects:: Commands for object-oriented programming.
12216 @end menu
12217
12218 @node Functions Commands
12219 @subsection Functions and Similar Entities
12220
12221 This section describes the commands for describing functions and similar
12222 entities:@refill
12223
12224 @table @code
12225 @findex deffn
12226 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
12227 The @code{@@deffn} command is the general definition command for
12228 functions, interactive commands, and similar entities that may take
12229 arguments. You must choose a term to describe the category of entity
12230 being defined; for example, ``Function'' could be used if the entity is
12231 a function. The @code{@@deffn} command is written at the beginning of a
12232 line and is followed on the same line by the category of entity being
12233 described, the name of this particular entity, and its arguments, if
12234 any. Terminate the definition with @code{@@end deffn} on a line of its
12235 own.@refill
12236
12237 @need 750
12238 For example, here is a definition:
12239
12240 @example
12241 @group
12242 @@deffn Command forward-char nchars
12243 Move point forward @@var@{nchars@} characters.
12244 @@end deffn
12245 @end group
12246 @end example
12247
12248 @noindent
12249 This shows a rather terse definition for a ``command'' named
12250 @code{forward-char} with one argument, @var{nchars}.
12251
12252 @code{@@deffn} and prints argument names such as @var{nchars} in slanted
12253 type in the printed output, because we think of these names as
12254 metasyntactic variables---they stand for the actual argument values.
12255 Within the text of the description, however, write an argument name
12256 explicitly with @code{@@var} to refer to the value of the argument.
12257 In the example above, we used @samp{@@var@{nchars@}} in this way.
12258
12259 In the unusual case when an argument name contains @samp{--}, or
12260 another character sequence which is treated specially
12261 (@pxref{Conventions}), use @code{@@var} around the argument. This
12262 causes the name to be printed in slanted typewriter, instead of the
12263 regular slanted font, exactly as input.
12264 @c except for ?` and !`, but we won't explain that.
12265
12266 The template for @code{@@deffn} is:
12267
12268 @example
12269 @group
12270 @@deffn @var{category} @var{name} @var{arguments}@dots{}
12271 @var{body-of-definition}
12272 @@end deffn
12273 @end group
12274 @end example
12275
12276 @findex defun
12277 @item @@defun @var{name} @var{arguments}@dots{}
12278 The @code{@@defun} command is the definition command for functions.
12279 @code{@@defun} is equivalent to @samp{@@deffn Function @dots{}}.
12280 Terminate the definition with @code{@@end defun} on a line of its own.
12281 Thus, the template is:
12282
12283 @example
12284 @group
12285 @@defun @var{function-name} @var{arguments}@dots{}
12286 @var{body-of-definition}
12287 @@end defun
12288 @end group
12289 @end example
12290
12291 @findex defmac
12292 @item @@defmac @var{name} @var{arguments}@dots{}
12293 The @code{@@defmac} command is the definition command for macros.
12294 @code{@@defmac} is equivalent to @samp{@@deffn Macro @dots{}} and
12295 works like @code{@@defun}.
12296
12297 @findex defspec
12298 @item @@defspec @var{name} @var{arguments}@dots{}
12299 The @code{@@defspec} command is the definition command for special
12300 forms. (In Lisp, a special form is an entity much like a function,
12301 @pxref{Special Forms,,, lispref, XEmacs Lisp Reference Manual}.)
12302 @code{@@defspec} is equivalent to @samp{@@deffn @{Special Form@}
12303 @dots{}} and works like @code{@@defun}.
12304 @end table
12305
12306 All these commands create entries in the index of functions.
12307
12308
12309 @node Variables Commands
12310 @subsection Variables and Similar Entities
12311
12312 Here are the commands for defining variables and similar
12313 entities:@refill
12314
12315 @table @code
12316 @findex defvr
12317 @item @@defvr @var{category} @var{name}
12318 The @code{@@defvr} command is a general definition command for
12319 something like a variable---an entity that records a value. You must
12320 choose a term to describe the category of entity being defined; for
12321 example, ``Variable'' could be used if the entity is a variable.
12322 Write the @code{@@defvr} command at the beginning of a line and
12323 follow it on the same line by the category of the entity and the
12324 name of the entity.
12325
12326 Capitalize the category name like a title. If the name of the category
12327 contains spaces, as in the name ``User Option'', enclose it in braces.
12328 Otherwise, the second word will be mistaken for the name of the entity.
12329 For example,
12330
12331 @example
12332 @group
12333 @@defvr @{User Option@} fill-column
12334 This buffer-local variable specifies
12335 the maximum width of filled lines.
12336 @dots{}
12337 @@end defvr
12338 @end group
12339 @end example
12340
12341 Terminate the definition with @code{@@end defvr} on a line of its
12342 own.@refill
12343
12344 The template is:
12345
12346 @example
12347 @group
12348 @@defvr @var{category} @var{name}
12349 @var{body-of-definition}
12350 @@end defvr
12351 @end group
12352 @end example
12353
12354 @code{@@defvr} creates an entry in the index of variables for @var{name}.
12355
12356 @findex defvar
12357 @item @@defvar @var{name}
12358 The @code{@@defvar} command is the definition command for variables.
12359 @code{@@defvar} is equivalent to @samp{@@defvr Variable
12360 @dots{}}.@refill
12361
12362 @need 750
12363 For example:
12364
12365 @example
12366 @group
12367 @@defvar kill-ring
12368 @dots{}
12369 @@end defvar
12370 @end group
12371 @end example
12372
12373 The template is:
12374
12375 @example
12376 @group
12377 @@defvar @var{name}
12378 @var{body-of-definition}
12379 @@end defvar
12380 @end group
12381 @end example
12382
12383 @code{@@defvar} creates an entry in the index of variables for
12384 @var{name}.@refill
12385
12386 @findex defopt
12387 @item @@defopt @var{name}
12388 @cindex User options, marking
12389 The @code{@@defopt} command is the definition command for @dfn{user
12390 options}, i.e., variables intended for users to change according to
12391 taste; XEmacs has many such (@pxref{Variables,,, xemacs, XEmacs User's
12392 Manual}). @code{@@defopt} is equivalent to @samp{@@defvr @{User
12393 Option@} @dots{}} and works like @code{@@defvar}. It creates an entry
12394 in the index of variables.
12395 @end table
12396
12397
12398 @node Typed Functions
12399 @subsection Functions in Typed Languages
12400
12401 The @code{@@deftypefn} command and its variations are for describing
12402 functions in languages in which you must declare types of variables and
12403 functions, such as C and C++.
12404
12405 @table @code
12406 @findex deftypefn
12407 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
12408 The @code{@@deftypefn} command is the general definition command for
12409 functions and similar entities that may take arguments and that are
12410 typed. The @code{@@deftypefn} command is written at the beginning of
12411 a line and is followed on the same line by the category of entity
12412 being described, the type of the returned value, the name of this
12413 particular entity, and its arguments, if any.@refill
12414
12415 @need 800
12416 @noindent
12417 For example,
12418
12419 @example
12420 @group
12421 @@deftypefn @{Library Function@} int foobar
12422 (int @@var@{foo@}, float @@var@{bar@})
12423 @dots{}
12424 @@end deftypefn
12425 @end group
12426 @end example
12427
12428 @need 1000
12429 @noindent
12430 (where the text before the ``@dots{}'', shown above as two lines, would
12431 actually be a single line in a real Texinfo file) produces the following
12432 in Info:
12433
12434 @smallexample
12435 @group
12436 -- Library Function: int foobar (int FOO, float BAR)
12437 @dots{}
12438 @end group
12439 @end smallexample
12440 @iftex
12441
12442 In a printed manual, it produces:
12443
12444 @quotation
12445 @deftypefn {Library Function} int foobar (int @var{foo}, float @var{bar})
12446 @dots{}
12447 @end deftypefn
12448 @end quotation
12449 @end iftex
12450
12451 This means that @code{foobar} is a ``library function'' that returns an
12452 @code{int}, and its arguments are @var{foo} (an @code{int}) and
12453 @var{bar} (a @code{float}).@refill
12454
12455 Since in typed languages, the actual names of the arguments are
12456 typically scattered among data type names and keywords, Texinfo cannot
12457 find them without help. You can either (a)@tie{}write everything
12458 as straight text, and it will be printed in slanted type; (b)@tie{}use
12459 @code{@@var} for the variable names, which will uppercase the
12460 variable names in Info and use the slanted typewriter font in printed
12461 output; (c)@tie{}use @code{@@var} for the variable names and
12462 @code{@@code} for the type names and keywords, which will be dutifully
12463 obeyed.
12464
12465 The template for @code{@@deftypefn} is:@refill
12466
12467 @example
12468 @group
12469 @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments} @dots{}
12470 @var{body-of-description}
12471 @@end deftypefn
12472 @end group
12473 @end example
12474
12475 @noindent
12476 Note that if the @var{category} or @var{data type} is more than one
12477 word then it must be enclosed in braces to make it a single argument.@refill
12478
12479 If you are describing a procedure in a language that has packages,
12480 such as Ada, you might consider using @code{@@deftypefn} in a manner
12481 somewhat contrary to the convention described in the preceding
12482 paragraphs. For example:
12483
12484 @example
12485 @group
12486 @@deftypefn stacks private push @@
12487 (@@var@{s@}:in out stack; @@
12488 @@var@{n@}:in integer)
12489 @dots{}
12490 @@end deftypefn
12491 @end group
12492 @end example
12493
12494 @noindent
12495 (The @code{@@deftypefn} arguments are shown using continuations
12496 (@pxref{Def Cmd Continuation Lines}), but could be on a single line in
12497 a real Texinfo file.)
12498
12499 In this instance, the procedure is classified as belonging to the
12500 package @code{stacks} rather than classified as a `procedure' and its
12501 data type is described as @code{private}. (The name of the procedure
12502 is @code{push}, and its arguments are @var{s} and @var{n}.)@refill
12503
12504 @code{@@deftypefn} creates an entry in the index of functions for
12505 @var{name}.
12506
12507 @item @@deftypefun @var{data-type} @var{name} @var{arguments}@dots{}
12508 @findex deftypefun
12509 The @code{@@deftypefun} command is the specialized definition command
12510 for functions in typed languages. The command is equivalent to
12511 @samp{@@deftypefn Function @dots{}}. The template is:
12512
12513 @example
12514 @group
12515 @@deftypefun @var{type} @var{name} @var{arguments}@dots{}
12516 @var{body-of-description}
12517 @@end deftypefun
12518 @end group
12519 @end example
12520
12521 @code{@@deftypefun} creates an entry in the index of functions for
12522 @var{name}.
12523
12524 @end table
12525
12526
12527 @node Typed Variables
12528 @subsection Variables in Typed Languages
12529
12530 Variables in typed languages are handled in a manner similar to
12531 functions in typed languages. @xref{Typed Functions}. The general
12532 definition command @code{@@deftypevr} corresponds to
12533 @code{@@deftypefn} and the specialized definition command
12534 @code{@@deftypevar} corresponds to @code{@@deftypefun}.@refill
12535
12536 @table @code
12537 @findex deftypevr
12538 @item @@deftypevr @var{category} @var{data-type} @var{name}
12539 The @code{@@deftypevr} command is the general definition command for
12540 something like a variable in a typed language---an entity that records
12541 a value. You must choose a term to describe the category of the
12542 entity being defined; for example, ``Variable'' could be used if the
12543 entity is a variable.@refill
12544
12545 The @code{@@deftypevr} command is written at the beginning of a line
12546 and is followed on the same line by the category of the entity
12547 being described, the data type, and the name of this particular
12548 entity.@refill
12549
12550 @need 800
12551 @noindent
12552 For example:
12553
12554 @example
12555 @group
12556 @@deftypevr @{Global Flag@} int enable
12557 @dots{}
12558 @@end deftypevr
12559 @end group
12560 @end example
12561
12562 @noindent
12563 produces the following in Info:
12564
12565 @example
12566 @group
12567 -- Global Flag: int enable
12568 @dots{}
12569 @end group
12570 @end example
12571 @iftex
12572
12573 @noindent
12574 and the following in a printed manual:
12575
12576 @quotation
12577 @deftypevr {Global Flag} int enable
12578 @dots{}
12579 @end deftypevr
12580 @end quotation
12581 @end iftex
12582
12583 @need 800
12584 The template is:
12585
12586 @example
12587 @@deftypevr @var{category} @var{data-type} @var{name}
12588 @var{body-of-description}
12589 @@end deftypevr
12590 @end example
12591
12592 @findex deftypevar
12593 @item @@deftypevar @var{data-type} @var{name}
12594 The @code{@@deftypevar} command is the specialized definition command
12595 for variables in typed languages. @code{@@deftypevar} is equivalent
12596 to @samp{@@deftypevr Variable @dots{}}. The template is:
12597
12598 @example
12599 @group
12600 @@deftypevar @var{data-type} @var{name}
12601 @var{body-of-description}
12602 @@end deftypevar
12603 @end group
12604 @end example
12605 @end table
12606
12607 These commands create entries in the index of variables.
12608
12609 @node Data Types
12610 @subsection Data Types
12611
12612 Here is the command for data types:@refill
12613
12614 @table @code
12615 @findex deftp
12616 @item @@deftp @var{category} @var{name} @var{attributes}@dots{}
12617 The @code{@@deftp} command is the generic definition command for data
12618 types. The command is written at the beginning of a line and is
12619 followed on the same line by the category, by the name of the type
12620 (which is a word like @code{int} or @code{float}), and then by names of
12621 attributes of objects of that type. Thus, you could use this command
12622 for describing @code{int} or @code{float}, in which case you could use
12623 @code{data type} as the category. (A data type is a category of
12624 certain objects for purposes of deciding which operations can be
12625 performed on them.)@refill
12626
12627 In Lisp, for example, @dfn{pair} names a particular data
12628 type, and an object of that type has two slots called the
12629 @sc{car} and the @sc{cdr}. Here is how you would write the first line
12630 of a definition of @code{pair}.@refill
12631
12632 @example
12633 @group
12634 @@deftp @{Data type@} pair car cdr
12635 @dots{}
12636 @@end deftp
12637 @end group
12638 @end example
12639
12640 @need 950
12641 The template is:
12642
12643 @example
12644 @group
12645 @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
12646 @var{body-of-definition}
12647 @@end deftp
12648 @end group
12649 @end example
12650
12651 @code{@@deftp} creates an entry in the index of data types.
12652 @end table
12653
12654
12655 @node Abstract Objects
12656 @subsection Object-Oriented Programming
12657
12658 @cindex Object-oriented programming
12659
12660 Here are the commands for formatting descriptions about abstract
12661 objects, such as are used in object-oriented programming. A class is
12662 a defined type of abstract object. An instance of a class is a
12663 particular object that has the type of the class. An instance
12664 variable is a variable that belongs to the class but for which each
12665 instance has its own value.
12666
12667 @menu
12668 * Variables: Object-Oriented Variables.
12669 * Methods: Object-Oriented Methods.
12670 @end menu
12671
12672
12673 @node Object-Oriented Variables
12674 @subsubsection Object-Oriented Variables
12675
12676 @cindex Variables, object-oriented
12677
12678 These commands allow you to define different sorts of variables in
12679 object-oriented programming languages.
12680
12681 @table @code
12682 @item @@defcv @var{category} @var{class} @var{name}
12683 @findex defcv
12684 The @code{@@defcv} command is the general definition command for
12685 variables associated with classes in object-oriented programming. The
12686 @code{@@defcv} command is followed by three arguments: the category of
12687 thing being defined, the class to which it belongs, and its
12688 name. For instance:
12689
12690 @example
12691 @group
12692 @@defcv @{Class Option@} Window border-pattern
12693 @dots{}
12694 @@end defcv
12695 @end group
12696 @end example
12697
12698 @noindent produces:
12699 @defcv {Class Option} Window border-pattern
12700 @dots{}
12701 @end defcv
12702
12703 @code{@@defcv} creates an entry in the index of variables.
12704
12705 @item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
12706 @findex deftypecv
12707 The @code{@@deftypecv} command is the definition command for typed
12708 class variables in object-oriented programming. It is analogous to
12709 @code{@@defcv} with the addition of the @var{data-type} parameter to
12710 specify the type of the instance variable. Ordinarily, the data type
12711 is a programming language construct that should be marked with
12712 @code{@@code}. For instance:
12713
12714 @example
12715 @group
12716 @@deftypecv @{Class Option@} Window @@code@{int@} border-pattern
12717 @dots{}
12718 @@end deftypecv
12719 @end group
12720 @end example
12721
12722 @noindent produces:
12723
12724 @deftypecv {Class Option} Window @code{int} border-pattern
12725 @dots{}
12726 @end deftypecv
12727
12728 @code{@@deftypecv} creates an entry in the index of variables.
12729
12730 @item @@defivar @var{class} @var{name}
12731 @findex defivar
12732 The @code{@@defivar} command is the definition command for instance
12733 variables in object-oriented programming. @code{@@defivar} is
12734 equivalent to @samp{@@defcv @{Instance Variable@} @dots{}}. For
12735 instance:
12736
12737 @example
12738 @group
12739 @@defivar Window border-pattern
12740 @dots{}
12741 @@end defivar
12742 @end group
12743 @end example
12744
12745 @noindent produces:
12746
12747 @defivar Window border-pattern
12748 @dots{}
12749 @end defivar
12750
12751 @code{@@defivar} creates an entry in the index of variables.
12752
12753 @item @@deftypeivar @var{class} @var{data-type} @var{name}
12754 @findex deftypeivar
12755 The @code{@@deftypeivar} command is the definition command for typed
12756 instance variables in object-oriented programming. It is analogous to
12757 @code{@@defivar} with the addition of the @var{data-type} parameter to
12758 specify the type of the instance variable. Ordinarily, the data type
12759 is a programming language construct that should be marked with
12760 @code{@@code}. For instance:
12761
12762 @example
12763 @group
12764 @@deftypeivar Window @@code@{int@} border-pattern
12765 @dots{}
12766 @@end deftypeivar
12767 @end group
12768 @end example
12769
12770 @noindent produces:
12771
12772 @deftypeivar Window @code{int} border-pattern
12773 @dots{}
12774 @end deftypeivar
12775
12776 @code{@@deftypeivar} creates an entry in the index of variables.
12777
12778 @end table
12779
12780 @node Object-Oriented Methods
12781 @subsubsection Object-Oriented Methods
12782
12783 @cindex Methods, object-oriented
12784
12785 These commands allow you to define different sorts of function-like
12786 entities resembling methods in object-oriented programming languages.
12787 These entities take arguments, as functions do, but are associated with
12788 particular classes of objects.
12789
12790 @table @code
12791
12792 @findex defop
12793 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
12794 The @code{@@defop} command is the general definition command for these
12795 method-like entities.
12796
12797 For example, some systems have constructs called @dfn{wrappers} that
12798 are associated with classes as methods are, but that act more like
12799 macros than like functions. You could use @code{@@defop Wrapper} to
12800 describe one of these.@refill
12801
12802 Sometimes it is useful to distinguish methods and @dfn{operations}.
12803 You can think of an operation as the specification for a method.
12804 Thus, a window system might specify that all window classes have a
12805 method named @code{expose}; we would say that this window system
12806 defines an @code{expose} operation on windows in general. Typically,
12807 the operation has a name and also specifies the pattern of arguments;
12808 all methods that implement the operation must accept the same
12809 arguments, since applications that use the operation do so without
12810 knowing which method will implement it.@refill
12811
12812 Often it makes more sense to document operations than methods. For
12813 example, window application developers need to know about the
12814 @code{expose} operation, but need not be concerned with whether a
12815 given class of windows has its own method to implement this operation.
12816 To describe this operation, you would write:@refill
12817
12818 @example
12819 @@defop Operation windows expose
12820 @end example
12821
12822 The @code{@@defop} command is written at the beginning of a line and
12823 is followed on the same line by the overall name of the category of
12824 operation, the name of the class of the operation, the name of the
12825 operation, and its arguments, if any.@refill
12826
12827 The template is:
12828 @example
12829 @group
12830 @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
12831 @var{body-of-definition}
12832 @@end defop
12833 @end group
12834 @end example
12835
12836 @code{@@defop} creates an entry, such as `@code{expose} on
12837 @code{windows}', in the index of functions.@refill
12838
12839 @findex deftypeop
12840 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
12841 The @code{@@deftypeop} command is the definition command for typed
12842 operations in object-oriented programming. It is similar to
12843 @code{@@defop} with the addition of the @var{data-type} parameter to
12844 specify the return type of the method. @code{@@deftypeop} creates an
12845 entry in the index of functions.
12846
12847 @item @@defmethod @var{class} @var{name} @var{arguments}@dots{}
12848 @findex defmethod
12849 The @code{@@defmethod} command is the definition command for methods
12850 in object-oriented programming. A method is a kind of function that
12851 implements an operation for a particular class of objects and its
12852 subclasses.
12853 @ignore
12854 @c ADR: Who cares?!?
12855 @c KB: Oh, I don't know, I think this info is crucial!
12856 In the Lisp Machine, methods actually were functions, but
12857 they were usually defined with @code{defmethod}.
12858 @end ignore
12859
12860 @code{@@defmethod} is equivalent to @samp{@@defop Method @dots{}}.
12861 The command is written at the beginning of a line and is followed by
12862 the name of the class of the method, the name of the method, and its
12863 arguments, if any.@refill
12864
12865 @noindent
12866 For example:
12867 @example
12868 @group
12869 @@defmethod @code{bar-class} bar-method argument
12870 @dots{}
12871 @@end defmethod
12872 @end group
12873 @end example
12874
12875 @noindent
12876 illustrates the definition for a method called @code{bar-method} of
12877 the class @code{bar-class}. The method takes an argument.
12878
12879 @code{@@defmethod} creates an entry in the index of functions.
12880
12881 @item @@deftypemethod @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
12882 @findex defmethod
12883 The @code{@@deftypemethod} command is the definition command for methods
12884 in object-oriented typed languages, such as C++ and Java. It is similar
12885 to the @code{@@defmethod} command with the addition of the
12886 @var{data-type} parameter to specify the return type of the method.
12887 @code{@@deftypemethod} creates an entry in the index of functions.
12888
12889 @end table
12890
12891
12892 @node Def Cmd Conventions
12893 @section Conventions for Writing Definitions
12894 @cindex Definition conventions
12895 @cindex Conventions for writing definitions
12896
12897 When you write a definition using @code{@@deffn}, @code{@@defun}, or
12898 one of the other definition commands, please take care to use
12899 arguments that indicate the meaning, as with the @var{count} argument
12900 to the @code{forward-word} function. Also, if the name of an argument
12901 contains the name of a type, such as @var{integer}, take care that the
12902 argument actually is of that type.@refill
12903
12904
12905 @node Sample Function Definition
12906 @section A Sample Function Definition
12907 @cindex Function definitions
12908 @cindex Command definitions
12909 @cindex Macro definitions
12910 @cindex Sample function definition
12911
12912 A function definition uses the @code{@@defun} and @code{@@end defun}
12913 commands. The name of the function follows immediately after the
12914 @code{@@defun} command and it is followed, on the same line, by the
12915 parameter list.@refill
12916
12917 Here is a definition from @ref{Calling Functions,,, lispref, XEmacs Lisp
12918 Reference Manual}.
12919
12920 @quotation
12921 @defun apply function &rest arguments
12922 @code{apply} calls @var{function} with @var{arguments}, just
12923 like @code{funcall} but with one difference: the last of
12924 @var{arguments} is a list of arguments to give to
12925 @var{function}, rather than a single argument. We also say
12926 that this list is @dfn{appended} to the other arguments.
12927
12928 @code{apply} returns the result of calling @var{function}.
12929 As with @code{funcall}, @var{function} must either be a Lisp
12930 function or a primitive function; special forms and macros
12931 do not make sense in @code{apply}.
12932
12933 @example
12934 (setq f 'list)
12935 @result{} list
12936 (apply f 'x 'y 'z)
12937 @error{} Wrong type argument: listp, z
12938 (apply '+ 1 2 '(3 4))
12939 @result{} 10
12940 (apply '+ '(1 2 3 4))
12941 @result{} 10
12942
12943 (apply 'append '((a b c) nil (x y z) nil))
12944 @result{} (a b c x y z)
12945 @end example
12946
12947 An interesting example of using @code{apply} is found in the description
12948 of @code{mapcar}.@refill
12949 @end defun
12950 @end quotation
12951
12952 @need 1200
12953 In the Texinfo source file, this example looks like this:
12954
12955 @example
12956 @group
12957 @@defun apply function &rest arguments
12958 @@code@{apply@} calls @@var@{function@} with
12959 @@var@{arguments@}, just like @@code@{funcall@} but with one
12960 difference: the last of @@var@{arguments@} is a list of
12961 arguments to give to @@var@{function@}, rather than a single
12962 argument. We also say that this list is @@dfn@{appended@}
12963 to the other arguments.
12964 @end group
12965
12966 @group
12967 @@code@{apply@} returns the result of calling
12968 @@var@{function@}. As with @@code@{funcall@},
12969 @@var@{function@} must either be a Lisp function or a
12970 primitive function; special forms and macros do not make
12971 sense in @@code@{apply@}.
12972 @end group
12973
12974 @group
12975 @@example
12976 (setq f 'list)
12977 @@result@{@} list
12978 (apply f 'x 'y 'z)
12979 @@error@{@} Wrong type argument: listp, z
12980 (apply '+ 1 2 '(3 4))
12981 @@result@{@} 10
12982 (apply '+ '(1 2 3 4))
12983 @@result@{@} 10
12984
12985 (apply 'append '((a b c) nil (x y z) nil))
12986 @@result@{@} (a b c x y z)
12987 @@end example
12988 @end group
12989
12990 @group
12991 An interesting example of using @@code@{apply@} is found
12992 in the description of @@code@{mapcar@}.
12993 @@end defun
12994 @end group
12995 @end example
12996
12997 @noindent
12998 In this manual, this function is listed in the Command and Variable
12999 Index under @code{apply}.@refill
13000
13001 Ordinary variables and user options are described using a format like
13002 that for functions except that variables do not take arguments.
13003
13004
13005 @node Conditionals
13006 @chapter Conditionally Visible Text
13007 @cindex Conditionally visible text
13008 @cindex Text, conditionally visible
13009 @cindex Visibility of conditional text
13010 @cindex If text conditionally visible
13011
13012 The @dfn{conditional commands} allow you to use different text for
13013 different output formats, or for general conditions that you define.
13014 For example, you can use them to specify different text for the
13015 printed manual and the Info output.
13016
13017 The conditional commands comprise the following categories.
13018
13019 @itemize @bullet
13020 @item
13021 Commands specific to an output format (Info, @TeX{}, HTML, @dots{}).
13022
13023 @item
13024 Commands specific to any output format @emph{other} than a given
13025 one (not Info, not @TeX{}, @dots{}).
13026
13027 @item
13028 `Raw' formatter text for any output format, passed straight
13029 through with no interpretation of @@-commands.
13030
13031 @item
13032 Format-independent variable substitutions, and testing if a variable
13033 is set or clear.
13034
13035 @end itemize
13036
13037 @menu
13038 * Conditional Commands:: Text for a given format.
13039 * Conditional Not Commands:: Text for any format other than a given one.
13040 * Raw Formatter Commands:: Using raw formatter commands.
13041 * set clear value:: Variable tests and substitutions.
13042 * Conditional Nesting:: Using conditionals inside conditionals.
13043 @end menu
13044
13045
13046 @node Conditional Commands
13047 @section Conditional Commands
13048
13049 Texinfo has an @code{@@if@var{format}} environment for each output
13050 format, to allow conditional inclusion of text for a particular output
13051 format.
13052
13053 @findex ifinfo
13054 @code{@@ifinfo} begins segments of text that should be ignored by
13055 @TeX{} when it typesets the printed manual, and by @command{makeinfo}
13056 when not producing Info output. The segment of text appears only in
13057 the Info file and, for historical compatibility, the plain text
13058 output.
13059
13060 @findex ifdocbook
13061 @findex ifhtml
13062 @findex ifplaintext
13063 @findex iftex
13064 @findex ifxml
13065 The environments for the other formats are analogous:
13066
13067 @table @code
13068 @item @@ifdocbook @dots{} @@end ifdocbook
13069 Text to appear only in the Docbook output.
13070
13071 @item @@ifhtml @dots{} @@end ifhtml
13072 Text to appear only in the HTML output.
13073
13074 @item @@ifplaintext @dots{} @@end ifplaintext
13075 Text to appear only in the plain text output.
13076
13077 @item @@iftex @dots{} @@end iftex
13078 Text to appear only in the printed manual.
13079
13080 @item @@ifxml @dots{} @@end ifxml
13081 Text to appear only in the XML output.
13082 @end table
13083
13084 The @code{@@if@dots{}} and @code{@@end if@dots{}} commands must appear
13085 on lines by themselves in your source file.
13086
13087 Here is an example showing all these conditionals:
13088
13089 @example
13090 @@iftex
13091 This text will appear only in the printed manual.
13092 @@end iftex
13093 @@ifinfo
13094 However, this text will appear only in Info and plain text.
13095 @@end ifinfo
13096 @@ifhtml
13097 And this text will only appear in HTML.
13098 @@end ifhtml
13099 @@ifplaintext
13100 Whereas this text will only appear in plain text.
13101 @@end ifplaintext
13102 @@ifxml
13103 Notwithstanding that this will only appear in XML.
13104 @@end ifxml
13105 @@ifdocbook
13106 Nevertheless, this will only appear in Docbook.
13107 @@end ifdocbook
13108 @end example
13109
13110 @noindent
13111 The preceding example produces the following line:
13112
13113 @iftex
13114 This text will appear only in the printed manual.
13115 @end iftex
13116 @ifinfo
13117 However, this text will appear only in Info and plain text.
13118 @end ifinfo
13119 @ifhtml
13120 And this text will only appear in HTML.
13121 @end ifhtml
13122 @ifplaintext
13123 Whereas this text will only appear in plain text.
13124 @end ifplaintext
13125 @ifxml
13126 Notwithstanding that this will only appear in XML.
13127 @end ifxml
13128 @ifdocbook
13129 Nevertheless, this will only appear in Docbook.
13130 @end ifdocbook
13131
13132 @noindent
13133 Notice that you only see one of the input lines, depending on which
13134 version of the manual you are reading.
13135
13136
13137 @node Conditional Not Commands
13138 @section Conditional Not Commands
13139 @findex ifnotdocbook
13140 @findex ifnothtml
13141 @findex ifnotinfo
13142 @findex ifnotplaintext
13143 @findex ifnottex
13144 @findex ifnotxml
13145
13146 You can specify text to be included in any output format @emph{other}
13147 than a given one with the @code{@@ifnot@dots{}} environments:
13148
13149 @example
13150 @@ifnotdocbook @dots{} @@end ifnotdocbook
13151 @@ifnothtml @dots{} @@end ifnothtml
13152 @@ifnotinfo @dots{} @@end ifnotinfo
13153 @@ifnotplaintext @dots{} @@end ifnotplaintext
13154 @@ifnottex @dots{} @@end ifnottex
13155 @@ifnotxml @dots{} @@end ifnotxml
13156 @end example
13157
13158 @noindent
13159 The @code{@@ifnot@dots{}} command and the @code{@@end} command must
13160 appear on lines by themselves in your actual source file.
13161
13162 If the output file is being made in the given format, the
13163 region is @emph{ignored}. Otherwise, it is included.
13164
13165 There is one exception (for historical compatibility):
13166 @code{@@ifnotinfo} text is omitted for both Info and plain text
13167 output, not just Info. To specify text which appears only in Info and
13168 not in plain text, use @code{@@ifnotplaintext}, like this:
13169
13170 @example
13171 @@ifinfo
13172 @@ifnotplaintext
13173 This will be in Info, but not plain text.
13174 @@end ifnotplaintext
13175 @@end ifinfo
13176 @end example
13177
13178 The regions delimited by these commands are ordinary Texinfo source as
13179 with @code{@@iftex}, not raw formatter source as with @code{@@tex}
13180 (@pxref{Raw Formatter Commands}).
13181
13182
13183 @node Raw Formatter Commands
13184 @section Raw Formatter Commands
13185 @cindex Raw formatter commands
13186 @cindex @TeX{} commands, using ordinary
13187 @cindex Ordinary @TeX{} commands, using
13188 @cindex Commands using raw @TeX{}
13189 @cindex Docbook, including raw
13190 @cindex HTML, including raw
13191 @cindex XML, including raw
13192 @cindex Plain @TeX{}
13193
13194 Inside a region delineated by @code{@@iftex} and @code{@@end iftex},
13195 you can embed some raw @TeX{} commands. The Texinfo processors will
13196 ignore such a region unless @TeX{} output is being produced. You can
13197 write the @TeX{} commands as you would write them in a normal @TeX{}
13198 file, except that you must replace the @samp{\} used by @TeX{} with an
13199 @samp{@@}. For example, in the @code{@@titlepage} section of a
13200 Texinfo file, you can use the @TeX{} command @code{@@vskip} to format
13201 the copyright page. (The @code{@@titlepage} command causes Info to
13202 ignore the region automatically, as it does with the @code{@@iftex}
13203 command.)
13204
13205 However, most features of plain @TeX{} will not work within
13206 @code{@@iftex}, as they are overridden by Texinfo features. The
13207 purpose of @code{@@iftex} is to provide conditional processing for the
13208 Texinfo source, not provide access to underlying formatting features.
13209
13210 @findex tex
13211 You can enter plain @TeX{} completely, and use @samp{\} in the @TeX{}
13212 commands, by delineating a region with the @code{@@tex} and @code{@@end
13213 tex} commands. All plain @TeX{} commands and category codes are
13214 restored within an @code{@@tex} region. The sole exception is that the
13215 @code{@@} character still introduces a command, so that @code{@@end tex}
13216 can be recognized properly. As with @code{@@iftex}, Texinfo
13217 processors will ignore such a region unless @TeX{} output is being produced.
13218
13219 @findex \gdef @r{within @code{@@tex}}
13220 In complex cases, you may wish to define new @TeX{} macros within
13221 @code{@@tex}. You must use @code{\gdef} to do this, not @code{\def},
13222 because @code{@@tex} regions are processed in a @TeX{} group.
13223
13224 @cindex Mathematical expressions
13225 As an example, here is a mathematical expression written in plain @TeX{}:
13226
13227 @example
13228 @@tex
13229 $$ \chi^2 = \sum_@{i=1@}^N
13230 \left (y_i - (a + b x_i)
13231 \over \sigma_i\right)^2 $$
13232 @@end tex
13233 @end example
13234
13235 @noindent
13236 The output of this example will appear only in a printed manual. If
13237 you are reading this in Info, you will not see the equation that appears
13238 in the printed manual.
13239 @iftex
13240 In a printed manual, the above expression looks like
13241 this:
13242 @end iftex
13243
13244 @tex
13245 $$ \chi^2 = \sum_{i=1}^N
13246 \left(y_i - (a + b x_i)
13247 \over \sigma_i\right)^2 $$
13248 @end tex
13249
13250 @findex ifhtml
13251 @findex html
13252 Analogously, you can use @code{@@ifhtml @dots{} @@end ifhtml} to delimit
13253 a region to be included in HTML output only, and @code{@@html @dots{}
13254 @@end html} for a region of raw HTML.
13255
13256 @findex ifxml
13257 @findex xml
13258 Likewise, you can use @code{@@ifxml @dots{} @@end ifxml} to delimit
13259 a region to be included in XML output only, and @code{@@xml @dots{}
13260 @@end xml} for a region of raw XML.
13261
13262 @findex ifdocbook
13263 @findex docbook
13264 Again likewise, you can use @code{@@ifdocbook @dots{} @@end ifdocbook}
13265 to delimit a region to be included in Docbook output only, and
13266 @code{@@docbook @dots{} @@end docbook} for a region of raw Docbook.
13267
13268 In all cases, the exception to the raw processing is that @code{@@} is
13269 still an escape character, so the @code{@@end} command can be
13270 recognized.
13271
13272
13273 @node set clear value
13274 @section @code{@@set}, @code{@@clear}, and @code{@@value}
13275
13276 You can direct the Texinfo formatting commands to format or ignore parts
13277 of a Texinfo file with the @code{@@set}, @code{@@clear}, @code{@@ifset},
13278 and @code{@@ifclear} commands.
13279
13280 Here are brief descriptions of these commands, see the following
13281 sections for more details:
13282
13283 @table @code
13284 @item @@set @var{flag} [@var{value}]
13285 Set the variable @var{flag}, to the optional @var{value} if specified.
13286
13287 @item @@clear @var{flag}
13288 Undefine the variable @var{flag}, whether or not it was previously defined.
13289
13290 @item @@ifset @var{flag}
13291 If @var{flag} is set, text through the next @code{@@end ifset} command
13292 is formatted. If @var{flag} is clear, text through the following
13293 @code{@@end ifset} command is ignored.
13294
13295 @item @@ifclear @var{flag}
13296 If @var{flag} is set, text through the next @code{@@end ifclear} command
13297 is ignored. If @var{flag} is clear, text through the following
13298 @code{@@end ifclear} command is formatted.
13299 @end table
13300
13301 @menu
13302 * set value:: Expand a flag variable to a string.
13303 * ifset ifclear:: Format a region if a flag is set.
13304 * value Example:: An easy way to update edition information.
13305 @end menu
13306
13307
13308 @node set value
13309 @subsection @code{@@set} and @code{@@value}
13310 @findex set
13311 @findex value
13312 @findex clear
13313
13314 You use the @code{@@set} command to specify a value for a flag, which
13315 is later expanded by the @code{@@value} command.
13316
13317 A @dfn{flag} (aka @dfn{variable}) is an identifier. It is best to use
13318 only letters and numerals in a flag name, not @samp{-} or
13319 @samp{_}---they will work in some contexts, but not all, due to
13320 limitations in @TeX{}.
13321
13322 The value is the remainder of the input line, and can contain anything.
13323
13324 Write the @code{@@set} command like this:
13325
13326 @example
13327 @@set foo This is a string.
13328 @end example
13329
13330 @noindent
13331 This sets the value of the flag @code{foo} to ``This is a string.''.
13332
13333 The Texinfo formatters then replace an @code{@@value@{@var{flag}@}}
13334 command with the string to which @var{flag} is set. Thus, when
13335 @code{foo} is set as shown above, the Texinfo formatters convert this:
13336
13337 @example
13338 @group
13339 @@value@{foo@}
13340 @exdent @r{to this:}
13341 This is a string.
13342 @end group
13343 @end example
13344
13345 You can write an @code{@@value} command within a paragraph; but you
13346 must write an @code{@@set} command on a line of its own.
13347
13348 If you write the @code{@@set} command like this:
13349
13350 @example
13351 @@set foo
13352 @end example
13353
13354 @noindent
13355 without specifying a string, the value of @code{foo} is the empty string.
13356
13357 If you clear a previously set flag with @code{@@clear @var{flag}}, a
13358 subsequent @code{@@value@{flag@}} command will report an error.
13359
13360 For example, if you set @code{foo} as follows:
13361
13362 @example
13363 @@set howmuch very, very, very
13364 @end example
13365
13366 @noindent
13367 then the formatters transform
13368
13369 @example
13370 @group
13371 It is a @@value@{howmuch@} wet day.
13372 @exdent @r{into}
13373 It is a very, very, very wet day.
13374 @end group
13375 @end example
13376
13377 If you write
13378
13379 @example
13380 @@clear howmuch
13381 @end example
13382
13383 @noindent
13384 then the formatters transform
13385
13386 @example
13387 @group
13388 It is a @@value@{howmuch@} wet day.
13389 @exdent @r{into}
13390 It is a @{No value for "howmuch"@} wet day.
13391 @end group
13392 @end example
13393
13394
13395 @node ifset ifclear
13396 @subsection @code{@@ifset} and @code{@@ifclear}
13397
13398 @findex ifset
13399 When a @var{flag} is set, the Texinfo formatting commands format text
13400 between subsequent pairs of @code{@@ifset @var{flag}} and @code{@@end
13401 ifset} commands. When the @var{flag} is cleared, the Texinfo formatting
13402 commands do @emph{not} format the text. @code{@@ifclear} operates
13403 analogously.
13404
13405 Write the conditionally formatted text between @code{@@ifset @var{flag}}
13406 and @code{@@end ifset} commands, like this:
13407
13408 @example
13409 @group
13410 @@ifset @var{flag}
13411 @var{conditional-text}
13412 @@end ifset
13413 @end group
13414 @end example
13415
13416 For example, you can create one document that has two variants, such as
13417 a manual for a `large' and `small' model:
13418
13419 @cindex Shrubbery
13420 @example
13421 You can use this machine to dig up shrubs
13422 without hurting them.
13423
13424 @@set large
13425
13426 @@ifset large
13427 It can also dig up fully grown trees.
13428 @@end ifset
13429
13430 Remember to replant promptly @dots{}
13431 @end example
13432
13433 @noindent
13434 In the example, the formatting commands will format the text between
13435 @code{@@ifset large} and @code{@@end ifset} because the @code{large}
13436 flag is set.
13437
13438 When @var{flag} is cleared, the Texinfo formatting commands do
13439 @emph{not} format the text between @code{@@ifset @var{flag}} and
13440 @code{@@end ifset}; that text is ignored and does not appear in either
13441 printed or Info output.
13442
13443 For example, if you clear the flag of the preceding example by writing
13444 an @code{@@clear large} command after the @code{@@set large} command
13445 (but before the conditional text), then the Texinfo formatting commands
13446 ignore the text between the @code{@@ifset large} and @code{@@end ifset}
13447 commands. In the formatted output, that text does not appear; in both
13448 printed and Info output, you see only the lines that say, ``You can use
13449 this machine to dig up shrubs without hurting them. Remember to replant
13450 promptly @dots{}''.
13451
13452 @findex ifclear
13453 If a flag is cleared with an @code{@@clear @var{flag}} command, then
13454 the formatting commands format text between subsequent pairs of
13455 @code{@@ifclear} and @code{@@end ifclear} commands. But if the flag
13456 is set with @code{@@set @var{flag}}, then the formatting commands do
13457 @emph{not} format text between an @code{@@ifclear} and an @code{@@end
13458 ifclear} command; rather, they ignore that text. An @code{@@ifclear}
13459 command looks like this:
13460
13461 @example
13462 @@ifclear @var{flag}
13463 @end example
13464
13465
13466 @node value Example
13467 @subsection @code{@@value} Example
13468
13469 You can use the @code{@@value} command to minimize the number of
13470 places you need to change when you record an update to a manual.
13471 @xref{GNU Sample Texts}, for the full text of an example of using this
13472 to work with Automake distributions.
13473
13474 This example is adapted from @ref{Top,, Overview, make, The GNU Make
13475 Manual}.
13476
13477 @enumerate
13478 @item
13479 Set the flags:
13480
13481 @example
13482 @group
13483 @@set EDITION 0.35 Beta
13484 @@set VERSION 3.63 Beta
13485 @@set UPDATED 14 August 1992
13486 @@set UPDATE-MONTH August 1992
13487 @end group
13488 @end example
13489
13490 @item
13491 Write text for the @code{@@copying} section (@pxref{copying}):
13492
13493 @example
13494 @group
13495 @@copying
13496 This is Edition @@value@{EDITION@},
13497 last updated @@value@{UPDATED@},
13498 of @@cite@{The GNU Make Manual@},
13499 for @@code@{make@}, version @@value@{VERSION@}.
13500
13501 Copyright @dots{}
13502
13503 Permission is granted @dots{}
13504 @@end copying
13505 @end group
13506 @end example
13507
13508 @item
13509 Write text for the title page, for people reading the printed manual:
13510
13511 @example
13512 @group
13513 @@titlepage
13514 @@title GNU Make
13515 @@subtitle A Program for Directing Recompilation
13516 @@subtitle Edition @@value@{EDITION@}, @dots{}
13517 @@subtitle @@value@{UPDATE-MONTH@}
13518 @@page
13519 @@insertcopying
13520 @dots{}
13521 @@end titlepage
13522 @end group
13523 @end example
13524
13525 @noindent
13526 (On a printed cover, a date listing the month and the year looks less
13527 fussy than a date listing the day as well as the month and year.)
13528
13529 @item
13530 Write text for the Top node, for people reading the Info file:
13531
13532 @example
13533 @group
13534 @@ifnottex
13535 @@node Top
13536 @@top Make
13537
13538 @@insertcopying
13539 @dots{}
13540 @@end ifnottex
13541 @end group
13542 @end example
13543
13544 After you format the manual, the @code{@@value} constructs have been
13545 expanded, so the output contains text like this:
13546
13547 @example
13548 @group
13549 This is Edition 0.35 Beta, last updated 14 August 1992,
13550 of `The GNU Make Manual', for `make', Version 3.63 Beta.
13551 @end group
13552 @end example
13553 @end enumerate
13554
13555 When you update the manual, you change only the values of the flags; you
13556 do not need to edit the three sections.
13557
13558
13559 @node Conditional Nesting
13560 @section Conditional Nesting
13561 @cindex Conditionals, nested
13562 @cindex Nesting conditionals
13563
13564 Conditionals can be nested; however, the details are a little tricky.
13565 The difficulty comes with failing conditionals, such as
13566 @code{@@ifhtml} when HTML is not being produced, where the included
13567 text is to be ignored. However, it is not to be @emph{completely}
13568 ignored, since it is useful to have one @code{@@ifset} inside another,
13569 for example---that is a way to include text only if two conditions are
13570 met. Here's an example:
13571
13572 @example
13573 @@ifset somevar
13574 @@ifset anothervar
13575 Both somevar and anothervar are set.
13576 @@end ifset
13577 @@ifclear anothervar
13578 Somevar is set, anothervar is not.
13579 @@end ifclear
13580 @@end ifset
13581 @end example
13582
13583 Technically, Texinfo requires that for a failing conditional, the
13584 ignored text must be properly nested with respect to that failing
13585 conditional. Unfortunately, it's not always feasible to check that
13586 @emph{all} conditionals are properly nested, because then the
13587 processors could have to fully interpret the ignored text, which
13588 defeats the purpose of the command. Here's an example illustrating
13589 these rules:
13590
13591 @example
13592 @@ifset a
13593 @@ifset b
13594 @@ifclear ok - ok, ignored
13595 @@end junky - ok, ignored
13596 @@end ifset
13597 @@c WRONG - missing @@end ifset.
13598 @end example
13599
13600 Finally, as mentioned above, all conditional commands must be on lines
13601 by themselves, with no text (even spaces) before or after. Otherwise,
13602 the processors cannot reliably determine which commands to consider
13603 for nesting purposes.
13604
13605
13606 @node Internationalization
13607 @chapter Internationalization
13608
13609 @cindex Internationalization
13610 Texinfo has some support for writing in languages other than English,
13611 although this area still needs considerable work.
13612
13613 For a list of the various accented and special characters Texinfo
13614 supports, see @ref{Inserting Accents}.
13615
13616 @menu
13617 * documentlanguage:: Declaring the current language.
13618 * documentencoding:: Declaring the input encoding.
13619 @end menu
13620
13621
13622 @node documentlanguage
13623 @section @code{@@documentlanguage @var{ll}[_@var{cc}]}: Set the Document Language
13624
13625 @findex documentlanguage
13626 @cindex Language, declaring
13627 @cindex Locale, declaring
13628 @cindex Document language, declaring
13629
13630 The @code{@@documentlanguage} command declares the current document
13631 locale. Write it on a line by itself, near the beginning of the
13632 file, but after @code{@@setfilename}
13633 (@pxref{setfilename,,@code{@@setfilename}}):
13634
13635 @example
13636 @@documentlanguage @var{ll}[_@var{cc}]
13637 @end example
13638
13639 Include a two-letter ISO@tie{}639-2 language code (@var{ll}) following
13640 the command name, optionally followed by an underscore and two-letter
13641 ISO@tie{}3166 two-letter country code (@var{cc}). If you have a
13642 multilingual document, the intent is to be able to use this command
13643 multiple times, to declare each language change. If the command is
13644 not used at all, the default is @code{en_US} for US English.
13645
13646 As with GNU Gettext (@pxref{Top,,,gettext, Gettext}), if the country
13647 code is omitted, the main dialect is assumed where possible. For
13648 example, @code{de} is equivalent to @code{de_DE} (German as spoken in
13649 Germany).
13650
13651 @cindex Document strings, translation of
13652 For Info and other online output, this command changes the translation
13653 of various @dfn{document strings} such as ``see'' in cross-references
13654 (@pxref{Cross References}), ``Function' in defuns (@pxref{Definition
13655 Commands}), and so on. Some strings, such as ``Node:'', ``Next:'',
13656 ``Menu:'', etc., are keywords in Info output, so are not translated
13657 there; they are translated in other output formats.
13658
13659 @cindex @file{txi-@var{cc}.tex}
13660 For @TeX{}, this command causes a file @file{txi-@var{locale}.tex} to
13661 be read (if it exists). If @code{@@setdocumentlanguage} argument
13662 contains the optional @samp{_@var{cc}} suffix, this is tried first.
13663 For example, with @code{@@setdocumentlanguage de_DE}, @TeX{} first
13664 looks for @file{txi-de_DE.tex}, then @file{txi-de.tex}.
13665
13666 Such a @file{txi-*} file is intended to redefine the various English
13667 words used in @TeX{} output, such as `Chapter', `See', and so on. We
13668 are aware that individual words like these cannot always be translated
13669 in isolation, and that a very different strategy would be required for
13670 ideographic (among other) scripts. Help in improving Texinfo's
13671 language support is welcome.
13672
13673 @cindex Hyphenation patterns, language-dependent
13674 It would also be desirable for this command to also change @TeX{}'s
13675 ideas of the current hyphenation patterns (via the @TeX{} primitive
13676 @code{\language}), but this is unfortunately not currently
13677 implemented.
13678
13679 In September 2006, the W3C Internationalization Activity released a
13680 new recommendation for specifying languages:
13681 @url{http://www.rfc-editor.org/rfc/bcp/bcp47.txt}. When Gettext
13682 supports this new scheme, Texinfo will too.
13683
13684 @cindex ISO 639-2 language codes
13685 @cindex ISO 3166 country codes
13686 @cindex Language codes
13687 @cindex Country codes
13688 Since the lists of language codes and country codes are updated
13689 relatively frequently, we don't attempt to list them here. The valid
13690 language codes are on the official home page for ISO@tie{}639,
13691 @url{http://www.loc.gov/standards/iso639-2/}. The country codes and
13692 the official web site for ISO@tie{}3166 can be found via
13693 @url{http://en.wikipedia.org/wiki/ISO_3166}.
13694
13695
13696 @node documentencoding
13697 @section @code{@@documentencoding @var{enc}}: Set Input Encoding
13698
13699 @findex documentencoding
13700 @cindex Encoding, declaring
13701 @cindex Input encoding, declaring
13702 @cindex Character set, declaring
13703 @cindex Document input encoding
13704
13705 The @code{@@documentencoding} command declares the input document
13706 encoding. Write it on a line by itself, with a valid encoding
13707 specification following, near the beginning of the file but after
13708 @code{@@setfilename} (@pxref{setfilename,,@code{@@setfilename}}):
13709
13710 @example
13711 @@documentencoding @var{enc}
13712 @end example
13713
13714 At present, Texinfo supports only these encodings:
13715
13716 @table @code
13717 @item US-ASCII
13718 This has no particular effect, but it's included for completeness.
13719
13720 @itemx UTF-8
13721 The vast global character encoding, expressed in 8-bit bytes.
13722 The Texinfo processors have no deep knowledge of Unicode; for the most
13723 part, they just pass along the input they are given to the output.
13724
13725 @itemx ISO-8859-1
13726 @itemx ISO-8859-15
13727 @item ISO-8859-2
13728 These specify the standard encodings for Western European (the first
13729 two) and Eastern European languages (the third), respectively. ISO
13730 8859-15 replaces some little-used characters from 8859-1 (e.g.,
13731 precomposed fractions) with more commonly needed ones, such as the
13732 Euro symbol (@euro{}).
13733
13734 A full description of the encodings is beyond our scope here;
13735 one useful reference is @uref{http://czyborra.com/charsets/iso8859.html}.
13736
13737 @item koi8-r
13738 This is the commonly used encoding for the Russian language.
13739
13740 @item koi8-u
13741 This is the commonly used encoding for the Ukrainian language.
13742
13743 @end table
13744
13745 Specifying an encoding @var{enc} has the following effects:
13746
13747 @opindex --enable-encoding
13748 @cindex Local Variables: section, for encoding
13749 @cindex Info output, and encoding
13750 In Info output, unless the option @option{--disable-encoding} is given
13751 to @command{makeinfo}, a so-called `Local Variables' section
13752 (@pxref{File Variables,,,xemacs,XEmacs User's Manual}) is output
13753 including @var{enc}. This allows Info readers to set the encoding
13754 appropriately.
13755
13756 @example
13757 Local Variables:
13758 coding: @var{enc}
13759 End:
13760 @end example
13761
13762 Also, in Info and plain text output (barring
13763 @option{--disable-encoding}), accent constructs and special
13764 characters, such as @code{@@'e}, are output as the actual 8-bit
13765 character in the given encoding.
13766
13767 @cindex HTML output, and encodings
13768 @cindex @code{http-equiv}, and charset specification
13769 @cindex @code{<meta>} HTML tag, and charset specification
13770 In HTML output, a @samp{<meta>} tag is output, in the @samp{<head>}
13771 section of the HTML, that specifies @var{enc}. Web servers and
13772 browsers cooperate to use this information so the correct encoding is
13773 used to display the page, if supported by the system.
13774
13775 @example
13776 <meta http-equiv="Content-Type" content="text/html;
13777 charset=@var{enc}">
13778 @end example
13779
13780 In split HTML output, if @option{--transliterate-file-names} is
13781 given (@pxref{HTML Xref 8-bit Character Expansion}), the names of HTML
13782 files are formed by transliteration of the corresponding node names,
13783 using the specified encoding.
13784
13785 In XML and Docbook output, the given document encoding is written in
13786 the output file as usual with those formats.
13787
13788 In @TeX{} output, the characters which are supported in the standard
13789 Computer Modern fonts are output accordingly. (For example, this
13790 means using constructed accents rather than precomposed glyphs.)
13791 Using a missing character generates a warning message, as does
13792 specifying an unimplemented encoding.
13793
13794
13795 @node Defining New Texinfo Commands
13796 @chapter Defining New Texinfo Commands
13797 @cindex Macros
13798 @cindex Defining new Texinfo commands
13799 @cindex New Texinfo commands, defining
13800 @cindex Texinfo commands, defining new
13801 @cindex User-defined Texinfo commands
13802
13803 Texinfo provides several ways to define new commands:
13804
13805 @itemize @bullet
13806 @item
13807 A Texinfo @dfn{macro} allows you to define a new Texinfo command as any
13808 sequence of text and/or existing commands (including other macros). The
13809 macro can have any number of @dfn{parameters}---text you supply each
13810 time you use the macro.
13811
13812 Incidentally, these macros have nothing to do with the @code{@@defmac}
13813 command, which is for documenting macros in the subject of the manual
13814 (@pxref{Def Cmd Template}).
13815
13816 @item
13817 @samp{@@alias} is a convenient way to define a new name for an existing
13818 command.
13819
13820 @item
13821 @samp{@@definfoenclose} allows you to define new commands with
13822 customized output in the Info file.
13823
13824 @end itemize
13825
13826 @menu
13827 * Defining Macros:: Defining and undefining new commands.
13828 * Invoking Macros:: Using a macro, once you've defined it.
13829 * Macro Details:: Limitations of Texinfo macros.
13830 * alias:: Command aliases.
13831 * definfoenclose:: Customized highlighting.
13832 @end menu
13833
13834
13835 @node Defining Macros
13836 @section Defining Macros
13837 @cindex Defining macros
13838 @cindex Macro definitions
13839
13840 @findex macro
13841 You use the Texinfo @code{@@macro} command to define a macro, like this:
13842
13843 @example
13844 @@macro @var{macroname}@{@var{param1}, @var{param2}, @dots{}@}
13845 @var{text} @dots{} \@var{param1}\ @dots{}
13846 @@end macro
13847 @end example
13848
13849 The @dfn{parameters} @var{param1}, @var{param2}, @dots{} correspond to
13850 arguments supplied when the macro is subsequently used in the document
13851 (described in the next section).
13852
13853 @cindex Macro names, valid characters in
13854 @cindex Names of macros, valid characters of
13855 For a macro to work consistently with @TeX{}, @var{macroname} must
13856 consist entirely of letters: no digits, hyphens, underscores, or other
13857 special characters. So, we recommend using only letters. However,
13858 @command{makeinfo} will accept anything except @samp{@{@}_^=};
13859 @samp{_} and @samp{^} are excluded so that macros can be called in
13860 @code{@@math} mode without a following space
13861 (@pxref{math,,@code{@@math}}).
13862
13863 If a macro needs no parameters, you can define it either with an empty
13864 list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
13865 foo}).
13866
13867 @cindex Body of a macro
13868 @cindex Mutually recursive macros
13869 @cindex Recursion, mutual
13870 The definition or @dfn{body} of the macro can contain most Texinfo
13871 commands, including previously-defined macros. Not-yet-defined macro
13872 invocations are not allowed; thus, it is not possible to have mutually
13873 recursive Texinfo macros. Also, a macro definition that defines another
13874 macro does not work in @TeX{} due to limitations in the design of
13875 @code{@@macro}.
13876
13877 @cindex Parameters to macros
13878 In the macro body, instances of a parameter name surrounded by
13879 backslashes, as in @samp{\@var{param1}\} in the example above, are
13880 replaced by the corresponding argument from the macro invocation. You
13881 can use parameter names any number of times in the body, including zero.
13882
13883 @cindex Backslash in macros
13884 To get a single @samp{\} in the macro expansion, use @samp{\\}. Any
13885 other use of @samp{\} in the body yields a warning.
13886
13887 @cindex Spaces in macros
13888 @cindex Whitespace in macros
13889 The newlines after the @code{@@macro} line and before the @code{@@end
13890 macro} line are ignored, that is, not included in the macro body. All
13891 other whitespace is treated according to the usual Texinfo rules.
13892
13893 @cindex Recursive macro invocations
13894 @findex rmacro
13895 To allow a macro to be used recursively, that is, in an argument to a
13896 call to itself, you must define it with @samp{@@rmacro}, like this:
13897
13898 @example
13899 @@rmacro rmac @{arg@}
13900 a\arg\b
13901 @@end rmacro
13902 @dots{}
13903 @@rmac@{1@@rmac@{text@}2@}
13904 @end example
13905
13906 This produces the output `a1atextb2b'. With @samp{@@macro} instead of
13907 @samp{@@rmacro}, an error message is given.
13908
13909 @findex unmacro
13910 @cindex Macros, undefining
13911 @cindex Undefining macros
13912 You can undefine a macro @var{foo} with @code{@@unmacro @var{foo}}.
13913 It is not an error to undefine a macro that is already undefined.
13914 For example:
13915
13916 @example
13917 @@unmacro foo
13918 @end example
13919
13920
13921 @node Invoking Macros
13922 @section Invoking Macros
13923 @cindex Invoking macros
13924 @cindex Expanding macros
13925 @cindex Running macros
13926 @cindex Macro invocation
13927
13928 After a macro is defined (see the previous section), you can use
13929 (@dfn{invoke}) it in your document like this:
13930
13931 @example
13932 @@@var{macroname} @{@var{arg1}, @var{arg2}, @dots{}@}
13933 @end example
13934
13935 @noindent and the result will be just as if you typed the body of
13936 @var{macroname} at that spot. For example:
13937
13938 @example
13939 @@macro foo @{p, q@}
13940 Together: \p\ & \q\.
13941 @@end macro
13942 @@foo@{a, b@}
13943 @end example
13944
13945 @noindent produces:
13946
13947 @display
13948 Together: a & b.
13949 @end display
13950
13951 @cindex Backslash, and macros
13952 Thus, the arguments and parameters are separated by commas and delimited
13953 by braces; any whitespace after (but not before) a comma is ignored.
13954 The braces are required in the invocation (but not the definition), even
13955 when the macro takes no arguments, consistent with all other Texinfo
13956 commands. For example:
13957
13958 @example
13959 @@macro argless @{@}
13960 No arguments here.
13961 @@end macro
13962 @@argless@{@}
13963 @end example
13964
13965 @noindent produces:
13966
13967 @display
13968 No arguments here.
13969 @end display
13970
13971 @cindex Comma, in macro arguments
13972 Passing strings containing commas as macro arguments requires special
13973 care, since they should be properly @dfn{quoted} to prevent
13974 @command{makeinfo} from confusing them with argument separators. To
13975 manually quote a comma, prepend it with a backslash character, like
13976 this: @code{\,}. Alternatively, use the @code{@@comma} command
13977 (@pxref{Inserting a Comma}). However, to facilitate use of macros,
13978 @command{makeinfo} implements a set of rules called @dfn{automatic
13979 quoting}:
13980
13981 @enumerate 1
13982 @item If a macro takes only one argument, all commas in its invocation
13983 are quoted by default. For example:
13984
13985 @example
13986 @group
13987 @@macro FIXME@{text@}
13988 @@strong@{FIXME: \text\@}
13989 @@end macro
13990
13991 @@FIXME@{A nice feature, though it can be dangerous.@}
13992 @end group
13993 @end example
13994
13995 @noindent
13996 will produce the following output
13997
13998 @example
13999 @strong{FIXME: A nice feature, though it can be dangerous.}
14000 @end example
14001
14002 And indeed, it can. Namely, @command{makeinfo}
14003 does not control number of arguments passed to one-argument
14004 macros, so be careful when you invoke them.
14005
14006 @item If a macro invocation includes another command (including a
14007 recursive invocation of itself), any commas in the nested command
14008 invocation(s) are quoted by default. For example, in
14009
14010 @example
14011 @@say@{@@strong@{Yes, I do@}, person one@}
14012 @end example
14013
14014 the comma after @samp{Yes} is implicitly quoted. Here's another
14015 example, with a recursive macro:
14016
14017 @example
14018 @group
14019 @@rmacro cat@{a,b@}
14020 \a\\b\
14021 @@end rmacro
14022
14023 @@cat@{@@cat@{foo, bar@}, baz@}
14024 @end group
14025 @end example
14026
14027 @noindent
14028 will produce the string @samp{foobarbaz}.
14029
14030 @item Otherwise, a comma should be explicitly quoted, as above, to be
14031 treated as a part of an argument.
14032 @end enumerate
14033
14034 @cindex Braces, in macro arguments
14035 Other characters that need to be quoted in macro arguments are
14036 curly braces and backslash. For example
14037
14038 @example
14039 @@@var{macname} @{\\\@{\@}\,@}
14040 @end example
14041
14042 @noindent
14043 will pass the (almost certainly error-producing) argument
14044 @samp{\@{@},} to @var{macname}. However, commas in parameters, even
14045 if escaped by a backslash, might cause trouble in @TeX{}.
14046
14047 If the macro is defined to take a single argument, and is invoked
14048 without any braces, the entire rest of the line after the macro name is
14049 supplied as the argument. For example:
14050
14051 @example
14052 @@macro bar @{p@}
14053 Twice: \p\ & \p\.
14054 @@end macro
14055 @@bar aah
14056 @end example
14057
14058 @noindent produces:
14059
14060 @c Sorry for cheating, but let's not require macros to process the manual.
14061 @display
14062 Twice: aah & aah.
14063 @end display
14064
14065 If the macro is defined to take a single argument, and is invoked with
14066 braces, the braced text is passed as the argument, regardless of
14067 commas. For example:
14068
14069 @example
14070 @@macro bar @{p@}
14071 Twice: \p\ & \p\.
14072 @@end macro
14073 @@bar@{a,b@}
14074 @end example
14075
14076 @noindent produces:
14077
14078 @display
14079 Twice: a,b & a,b.
14080 @end display
14081
14082
14083 @node Macro Details
14084 @section Macro Details and Caveats
14085 @cindex Macro details
14086 @cindex Details of macro usage
14087 @cindex Caveats for macro usage
14088
14089 Due to unavoidable limitations, certain macro-related constructs cause
14090 problems with @TeX{}. If you get macro-related errors when producing
14091 the printed version of a manual, try expanding the macros with
14092 @command{makeinfo} by invoking @command{texi2dvi} with the @samp{-E}
14093 option (@pxref{Format with texi2dvi}).
14094
14095 @itemize @bullet
14096 @item
14097 As mentioned earlier, macro names must consist entirely of letters.
14098
14099 @item
14100 It is not advisable to redefine any @TeX{} primitive, plain, or
14101 Texinfo command name as a macro. Unfortunately this is a very large
14102 set of names, and the possible resulting errors are unpredictable.
14103
14104 @item
14105 All macros are expanded inside at least one @TeX{} group. This means
14106 that @code{@@set} and other such commands have no effect inside a
14107 macro.
14108
14109 @item
14110 Commas in macro arguments, even if escaped by a backslash, don't
14111 always work.
14112
14113 @item
14114 Macro arguments cannot cross lines.
14115
14116 @item
14117 It is (usually) best to avoid comments inside macro definitions, but
14118 see the next item.
14119
14120 @item
14121 Macros containing a command which must be on a line by itself, such as
14122 a conditional, cannot be invoked in the middle of a line. In general,
14123 the interaction of newlines in the macro definitions and invocations
14124 depends on the precise commands and context. You may be able to work
14125 around some problems with judicious use of @code{@@c}. Suppose you
14126 define a macro that is always intended to be used on a line by itself:
14127
14128 @example
14129 @@macro linemac
14130 @@cindex whatever
14131 @@c
14132 @@end macro
14133 ...
14134 foo
14135 @@linemac
14136 bar
14137 @end example
14138
14139 Without the @code{@@c}, there will be an unwanted blank line between
14140 the @samp{@@cindex whatever} and the @samp{bar} (one newline comes
14141 from the macro definition, one from after the invocation), causing a
14142 paragraph break.
14143
14144 On the other hand, you wouldn't want the @code{@@c} if the macro was
14145 sometimes invoked in the middle of a line (the text after the
14146 invocation would be treated as a comment).
14147
14148 @item
14149 In general, you can't arbitrarily substitute a macro call for Texinfo
14150 command arguments, even when the text is the same. It might work with
14151 some commands, it fails with others. Best not to do it at all. For
14152 instance, this fails:
14153
14154 @example
14155 @@macro offmacro
14156 off
14157 @@end macro
14158 @@headings @@offmacro
14159 @end example
14160
14161 @noindent
14162 You would expect this to be equivalent to @code{@@headings off}, but
14163 for @TeX{}nical reasons, it fails with a mysterious error message
14164 (@code{Paragraph ended before @@headings was complete}).
14165
14166 @item
14167 Macros cannot define macros in the natural way. To do this, you must
14168 use conditionals and raw @TeX{}. For example:
14169
14170 @example
14171 @@ifnottex
14172 @@macro ctor @{name, arg@}
14173 @@macro \name\
14174 something involving \arg\ somehow
14175 @@end macro
14176 @@end macro
14177 @@end ifnottex
14178 @@tex
14179 \gdef\ctor#1@{\ctorx#1,@}
14180 \gdef\ctorx#1,#2,@{\def#1@{something involving #2 somehow@}@}
14181 @@end tex
14182 @end example
14183
14184 @end itemize
14185
14186 The @command{makeinfo} implementation also has limitations:
14187
14188 @itemize
14189 @item
14190 @code{@@verbatim} and macros do not mix; for instance, you can't start
14191 a verbatim block inside a macro and end it outside.
14192 (@xref{verbatim}.) Starting any environment inside a macro and ending
14193 it outside may or may not work, for that matter.
14194
14195 @item
14196 Macros that completely define macros are ok, but it's not possible to
14197 have incorrectly nested macro definitions. That is, @code{@@macro}
14198 and @code{@@end macro} (likewise for @code{@@rmacro}) must be
14199 correctly paired. For example, you cannot start a macro definition
14200 within a macro, and then end the nested definition outside the macro.
14201
14202 @item
14203 @code{@@rmacro} is a kludge.
14204
14205 @end itemize
14206
14207 One more limitation is common to both implementations: white space is
14208 ignored at the beginnings of lines.
14209
14210 Future major revisions of Texinfo may ease some of these limitations
14211 (by introducing a new macro syntax).
14212
14213
14214 @node alias
14215 @section @samp{@@alias @var{new}=@var{existing}}
14216 @cindex Aliases, command
14217 @cindex Command aliases
14218 @findex alias
14219
14220 The @samp{@@alias} command defines a new command to be just like an
14221 existing one. This is useful for defining additional markup names, thus
14222 preserving semantic information in the input even though the output
14223 result may be the same.
14224
14225 Write the @samp{@@alias} command on a line by itself, followed by the
14226 new command name, an equals sign, and the existing command name.
14227 Whitespace around the equals sign is ignored. Thus:
14228 @example
14229 @@alias @var{new} = @var{existing}
14230 @end example
14231
14232 For example, if your document contains citations for both books and
14233 some other media (movies, for example), you might like to define a
14234 macro @code{@@moviecite@{@}} that does the same thing as an ordinary
14235 @code{@@cite@{@}} but conveys the extra semantic information as well.
14236 You'd do this as follows:
14237
14238 @example
14239 @@alias moviecite = cite
14240 @end example
14241
14242 Macros do not always have the same effect as aliases, due to vagaries
14243 of argument parsing. Also, aliases are much simpler to define than
14244 macros. So the command is not redundant. (It was also heavily used
14245 in the Jargon File!)
14246
14247 Aliases must not be recursive, directly or indirectly.
14248
14249 It is not advisable to redefine any @TeX{} primitive, plain, or
14250 Texinfo command name as an alias. Unfortunately this is a very large
14251 set of names, and the possible resulting errors are completely random.
14252
14253
14254 @node definfoenclose
14255 @section @samp{definfoenclose}: Customized Highlighting
14256 @cindex Highlighting, customized
14257 @cindex Customized highlighting
14258 @findex definfoenclose
14259
14260 A @code{@@definfoenclose} command may be used to define a highlighting
14261 command for Info, but not for @TeX{}. A command defined using
14262 @code{@@definfoenclose} marks text by enclosing it in strings that
14263 precede and follow the text. You can use this to get closer control of
14264 your Info output.
14265
14266 Presumably, if you define a command with @code{@@definfoenclose} for Info,
14267 you will create a corresponding command for @TeX{}, either in
14268 @file{texinfo.tex}, @file{texinfo.cnf}, or within an @samp{@@iftex} in
14269 your document.
14270
14271 Write a @code{@@definfoenclose} command on a line and follow it with
14272 three arguments separated by commas. The first argument to
14273 @code{@@definfoenclose} is the @@-command name (without the @code{@@});
14274 the second argument is the Info start delimiter string; and the third
14275 argument is the Info end delimiter string. The latter two arguments
14276 enclose the highlighted text in the Info file. A delimiter string may
14277 contain spaces. Neither the start nor end delimiter is required. If
14278 you do not want a start delimiter but do want an end delimiter, you must
14279 follow the command name with two commas in a row; otherwise, the Info
14280 formatting commands will naturally misinterpret the end delimiter string
14281 you intended as the start delimiter string.
14282
14283 If you do a @code{@@definfoenclose} on the name of a predefined macro
14284 (such as @code{@@emph}, @code{@@strong}, @code{@@t}, or @code{@@i}), the
14285 enclosure definition will override the built-in definition.
14286
14287 An enclosure command defined this way takes one argument in braces; this
14288 is intended for new markup commands (@pxref{Marking Text}).
14289
14290 @findex phoo
14291 For example, you can write:
14292
14293 @example
14294 @@definfoenclose phoo,//,\\
14295 @end example
14296
14297 @noindent
14298 near the beginning of a Texinfo file to define @code{@@phoo} as an Info
14299 formatting command that inserts `//' before and `\\' after the argument
14300 to @code{@@phoo}. You can then write @code{@@phoo@{bar@}} wherever you
14301 want `//bar\\' highlighted in Info.
14302
14303 Also, for @TeX{} formatting, you could write
14304
14305 @example
14306 @@iftex
14307 @@global@@let@@phoo=@@i
14308 @@end iftex
14309 @end example
14310
14311 @noindent
14312 to define @code{@@phoo} as a command that causes @TeX{} to typeset the
14313 argument to @code{@@phoo} in italics.
14314
14315 Each definition applies to its own formatter: one for @TeX{}, the other
14316 for @code{texinfo-format-buffer} or @code{texinfo-format-region}. The
14317 @code{@@definfoenclose} command need not be within @samp{@@ifinfo}, but
14318 the raw @TeX{} commands do need to be in @samp{@@iftex}.
14319
14320 @findex headword
14321 Here is another example: write
14322
14323 @example
14324 @@definfoenclose headword, , :
14325 @end example
14326
14327 @noindent
14328 near the beginning of the file, to define @code{@@headword} as an Info
14329 formatting command that inserts nothing before and a colon after the
14330 argument to @code{@@headword}.
14331
14332 @samp{@@definfoenclose} definitions must not be recursive, directly or
14333 indirectly.
14334
14335
14336 @node Hardcopy
14337 @chapter Formatting and Printing Hardcopy
14338 @cindex Format and print hardcopy
14339 @cindex Printing hardcopy
14340 @cindex Hardcopy, printing it
14341 @cindex Making a printed manual
14342 @cindex Sorting indices
14343 @cindex Indices, sorting
14344 @cindex @TeX{} index sorting
14345 @pindex texindex
14346
14347 There are three major shell commands for making a printed manual from a
14348 Texinfo file: one for converting the Texinfo file into a file that will be
14349 printed, a second for sorting indices, and a third for printing the
14350 formatted document. When you use the shell commands, you can either
14351 work directly in the operating system shell or work within a shell
14352 inside XEmacs.
14353
14354 If you are using XEmacs, you can use commands provided by Texinfo
14355 mode instead of shell commands. In addition to the three commands to
14356 format a file, sort the indices, and print the result, Texinfo mode
14357 offers key bindings for commands to recenter the output buffer, show the
14358 print queue, and delete a job from the print queue.
14359
14360 @menu
14361 * Use TeX:: Use @TeX{} to format for hardcopy.
14362 * Format with tex/texindex:: How to format with explicit shell commands.
14363 * Format with texi2dvi:: A simpler way to format.
14364 * Print with lpr:: How to print.
14365 * Within XEmacs:: How to format and print from an XEmacs shell.
14366 * Texinfo Mode Printing:: How to format and print in Texinfo mode.
14367 * Compile-Command:: How to print using XEmacs's compile command.
14368 * Requirements Summary:: @TeX{} formatting requirements summary.
14369 * Preparing for TeX:: What to do before you use @TeX{}.
14370 * Overfull hboxes:: What are and what to do with overfull hboxes.
14371 * smallbook:: How to print small format books and manuals.
14372 * A4 Paper:: How to print on A4 or A5 paper.
14373 * pagesizes:: How to print with customized page sizes.
14374 * Cropmarks and Magnification:: How to print marks to indicate the size
14375 of pages and how to print scaled up output.
14376 * PDF Output:: Portable Document Format output.
14377 * Obtaining TeX:: How to Obtain @TeX{}.
14378 @end menu
14379
14380 @node Use TeX
14381 @section Use @TeX{}
14382
14383 The typesetting program called @TeX{} is used for formatting a Texinfo
14384 file. @TeX{} is a very powerful typesetting program and, if used correctly,
14385 does an exceptionally good job. (@xref{Obtaining TeX, , How to Obtain
14386 @TeX{}}, for information on how to obtain @TeX{}.)
14387
14388 The standalone @code{makeinfo} program and XEmacs functions
14389 @code{texinfo-format-region} and @code{texinfo-format-buffer} commands
14390 read the very same @@-commands in the Texinfo file as does @TeX{}, but
14391 process them differently to make an Info file (@pxref{Creating an Info
14392 File}).
14393
14394
14395 @node Format with tex/texindex
14396 @section Format with @code{tex} and @code{texindex}
14397 @cindex Shell formatting with @code{tex} and @code{texindex}
14398 @cindex Formatting with @code{tex} and @code{texindex}
14399 @cindex DVI file
14400
14401 You can format the Texinfo file with the shell command @code{tex}
14402 followed by the name of the Texinfo file. For example:
14403
14404 @example
14405 tex foo.texi
14406 @end example
14407
14408 @noindent
14409 @TeX{} will produce a @dfn{DVI file} as well as several auxiliary
14410 files containing information for indices, cross references, etc. The
14411 DVI file (for @dfn{DeVice Independent} file) can be printed on virtually
14412 any device (see the following sections).
14413
14414 @pindex texindex
14415 The @code{tex} formatting command itself does not sort the indices; it
14416 writes an output file of unsorted index data. To generate a printed
14417 index after running the @command{tex} command, you first need a sorted
14418 index to work from. The @command{texindex} command sorts indices.
14419 (The source file @file{texindex.c} comes as part of the standard
14420 Texinfo distribution, among other places.) (@command{texi2dvi} runs
14421 @command{tex} and @command{texindex} as necessary.)
14422
14423 @cindex Names of index files
14424 @cindex Index file names
14425 The @code{tex} formatting command outputs unsorted index files under
14426 names that obey a standard convention: the name of your main input file
14427 with any @samp{.tex} (or similar, @pxref{tex invocation,,, web2c,
14428 Web2c}) extension removed, followed by the two letter names of indices.
14429 For example, the raw index output files for the input file
14430 @file{foo.texinfo} would be @file{foo.cp}, @file{foo.vr}, @file{foo.fn},
14431 @file{foo.tp}, @file{foo.pg} and @file{foo.ky}. Those are exactly the
14432 arguments to give to @code{texindex}.
14433
14434 @need 1000
14435 @cindex Wildcards
14436 @cindex Globbing
14437 Instead of specifying all the unsorted index file names explicitly, you
14438 can use @samp{??} as shell wildcards and give the command in this
14439 form:
14440
14441 @example
14442 texindex foo.??
14443 @end example
14444
14445 @noindent
14446 This command will run @code{texindex} on all the unsorted index files,
14447 including any that you have defined yourself using @code{@@defindex}
14448 or @code{@@defcodeindex}. (You may execute @samp{texindex foo.??}
14449 even if there are similarly named files with two letter extensions
14450 that are not index files, such as @samp{foo.el}. The @code{texindex}
14451 command reports but otherwise ignores such files.)
14452
14453 For each file specified, @code{texindex} generates a sorted index file
14454 whose name is made by appending @samp{s} to the input file name. The
14455 @code{@@printindex} command looks for a file with that name
14456 (@pxref{Printing Indices & Menus}). @code{texindex} does not alter the
14457 raw index output file.
14458
14459 After you have sorted the indices, you need to rerun @code{tex} on the
14460 Texinfo file. This regenerates the DVI file, this time with
14461 up-to-date index entries.
14462
14463 Finally, you may need to run @code{tex} one more time, to get the page
14464 numbers in the cross-references correct.
14465
14466 To summarize, this is a five step process:
14467
14468 @enumerate
14469 @item
14470 Run @code{tex} on your Texinfo file. This generates a DVI file (with
14471 undefined cross-references and no indices), and the raw index files
14472 (with two letter extensions).
14473
14474 @item
14475 Run @code{texindex} on the raw index files. This creates the
14476 corresponding sorted index files (with three letter extensions).
14477
14478 @item
14479 Run @code{tex} again on your Texinfo file. This regenerates the DVI
14480 file, this time with indices and defined cross-references, but with page
14481 numbers for the cross-references from last time, generally incorrect.
14482
14483 @item
14484 Sort the indices again, with @code{texindex}.
14485
14486 @item
14487 Run @code{tex} one last time. This time the correct page numbers are
14488 written for the cross-references.
14489 @end enumerate
14490
14491 @pindex texi2dvi
14492 Alternatively, it's a one-step process: run @code{texi2dvi}
14493 (@pxref{Format with texi2dvi}).
14494
14495 You need not run @code{texindex} each time after you run @code{tex}. If
14496 you do not, on the next run, the @code{tex} formatting command will use
14497 whatever sorted index files happen to exist from the previous use of
14498 @code{texindex}. This is usually ok while you are debugging.
14499
14500 @cindex Auxiliary files, avoiding
14501 @findex novalidate
14502 @cindex Pointer validation, suppressing
14503 @cindex Chapters, formatting one at a time
14504 Sometimes you may wish to print a document while you know it is
14505 incomplete, or to print just one chapter of a document. In that case,
14506 the usual auxiliary files that @TeX{} creates and warnings @TeX{} gives
14507 when cross-references are not satisfied are just nuisances. You can
14508 avoid them with the @code{@@novalidate} command, which you must give
14509 @emph{before} the @code{@@setfilename} command
14510 (@pxref{setfilename,,@code{@@setfilename}}). Thus, the beginning of
14511 your file would look approximately like this:
14512
14513 @example
14514 \input texinfo
14515 @@novalidate
14516 @@setfilename myfile.info
14517 @dots{}
14518 @end example
14519
14520 @noindent @code{@@novalidate} also turns off validation in
14521 @code{makeinfo}, just like its @code{--no-validate} option
14522 (@pxref{Pointer Validation}).
14523
14524
14525 @node Format with texi2dvi
14526 @section Format with @code{texi2dvi}
14527 @pindex texi2dvi @r{(shell script)}
14528
14529 The @code{texi2dvi} command automatically runs both @TeX{} and
14530 @command{texindex} as many times as necessary to produce a DVI file
14531 with sorted indices and all cross-references resolved. It is
14532 therefore simpler than manually executing the
14533 @code{tex}---@code{texindex}---@code{tex}---@code{tex} sequence
14534 described in the previous section.
14535
14536 To run @code{texi2dvi} on an input file @file{foo.texi}, do this (where
14537 @samp{prompt$ } is your shell prompt):
14538
14539 @example
14540 prompt$ @kbd{texi2dvi foo.texi}
14541 @end example
14542
14543 As shown in this example, the input filenames to @code{texi2dvi} must
14544 include any extension (@samp{.texi}, @samp{.texinfo}, etc.). Under
14545 MS-DOS and perhaps in other circumstances, you may need to run @samp{sh
14546 texi2dvi foo.texi} instead of relying on the operating system to invoke
14547 the shell on the @samp{texi2dvi} script.
14548
14549 @opindex --command @r{(@command{texi2dvi})}
14550 One useful option to @code{texi2dvi} is @samp{--command=@var{cmd}}.
14551 This inserts @var{cmd} on a line by itself after the
14552 @code{@@setfilename} in a temporary copy of the input file before
14553 running @TeX{}. With this, you can specify different printing
14554 formats, such as @code{@@smallbook} (@pxref{smallbook}),
14555 @code{@@afourpaper} (@pxref{A4 Paper}), or @code{@@pagesizes}
14556 (@pxref{pagesizes}), without actually changing the document source.
14557 (You can also do this on a site-wide basis with @file{texinfo.cnf};
14558 @pxref{Preparing for TeX,,Preparing for @TeX{}}).
14559
14560 @opindex --pdf @r{(@command{texi2dvi})}
14561 With the @option{--pdf} option, @command{texi2dvi} produces PDF output
14562 instead of DVI (@pxref{PDF Output}), by running @command{pdftex}
14563 instead of @command{tex}. Alternatively, the command
14564 @command{texi2pdf} is an abbreviation for running @samp{texi2dvi
14565 --pdf}. The command @command{pdftexi2dvi} is also supported as a
14566 convenience to AUC-@TeX{} users, since the latter merely prepends
14567 @samp{pdf} to DVI producing tools to have PDF producing tools.
14568
14569 @cindex @LaTeX{}, processing with @command{texi2dvi}
14570 @command{texi2dvi} can also be used to process @LaTeX{} files; simply
14571 run @samp{texi2dvi filename.ext}.
14572
14573 @opindex --language @r{(@command{texi2dvi})}
14574 Normally @command{texi2dvi} is able to guess the input file language
14575 by its contents and file name suffix. If, however, it fails to do so
14576 you can specify the input language using
14577 @option{--language=@var{lang}} command line option, where @var{lang}
14578 is either @samp{latex} or @samp{texinfo}.
14579
14580 @command{texi2dvi} will use @command{etex} (or @command{pdfetex}) if
14581 they are available; these extended versions of @TeX{} are not
14582 required, and the DVI (or PDF) output is identical, but they simplify
14583 the @TeX{} programming in some cases, and provide additional tracing
14584 information when debugging @file{texinfo.tex}.
14585
14586 @opindex --translate-file @r{(@command{texi2dvi})}
14587 Several options are provided for handling documents, written in
14588 character sets other than ASCII. The
14589 @option{--translate-file=@var{file}} option instructs
14590 @command{texi2dvi} to translate input into internal @TeX{} character
14591 set using @dfn{translation file} @var{file} (@pxref{TCX files, TCX
14592 files, TCX files: Character translations, web2c, Web2c: A @TeX{}
14593 implementation}).
14594
14595 @opindex --recode @r{(@command{texi2dvi})}
14596 The options @option{--recode} and @option{--recode-from=@var{enc}}
14597 allow conversion of an input document before running @TeX{}. The
14598 @option{--recode} option recodes the document from encoding specified
14599 by @samp{@@documentencoding} command
14600 (@pxref{documentencoding,,@code{documentencoding}}) to plain 7-bit
14601 @samp{texinfo} encoding.
14602
14603 @opindex --recode-from @r{(@command{texi2dvi})}
14604 The option @option{--recode-from=@var{enc}} recodes the document from
14605 @var{enc} encoding to the encoding specified by
14606 @samp{@@documentencoding}. This is useful, for example, if the
14607 document is written in @samp{UTF-8} encoding and an equivalent 8-bit
14608 encoding is supported by @command{makeinfo}.
14609
14610 Both @option{--recode} and @option{--recode-from=@var{enc}} use
14611 @command{recode} utility to perform the conversion. If
14612 @command{recode} fails to process the file, @command{texi2dvi} prints
14613 a warning and continues using unmodified input file.
14614
14615 For a list of other options, run @samp{texi2dvi --help}.
14616
14617
14618 @node Print with lpr
14619 @section Shell Print Using @code{lpr -d}
14620 @pindex lpr @r{(DVI print command)}
14621
14622 The precise command to print a DVI file depends on your system
14623 installation. Two common ones are @samp{dvips foo.dvi -o} and @samp{lpr
14624 -d foo.dvi}.
14625
14626 For example, the following commands will (perhaps) suffice to sort the
14627 indices, format, and print the @cite{Bison Manual}:
14628
14629 @example
14630 @group
14631 tex bison.texinfo
14632 texindex bison.??
14633 tex bison.texinfo
14634 lpr -d bison.dvi
14635 @end group
14636 @end example
14637
14638 @noindent
14639 (Remember that the shell commands may be different at your site; but
14640 these are commonly used versions.)
14641
14642 Using the @code{texi2dvi} shell script (see the previous section):
14643
14644 @example
14645 @group
14646 texi2dvi bison.texinfo
14647 lpr -d bison.dvi
14648 # or perhaps dvips bison.dvi -o
14649 @end group
14650 @end example
14651
14652 @cindex Shell printing, on MS-DOS/MS-Windows
14653 @cindex Printing DVI files, on MS-DOS/MS-Windows
14654 @pindex lpr@r{-d, replacements on MS-DOS/MS-Windows}
14655 @code{lpr} is a standard program on Unix systems, but it is usually
14656 absent on MS-DOS/MS-Windows. Some network packages come with a
14657 program named @code{lpr}, but these are usually limited to sending files
14658 to a print server over the network, and generally don't support the
14659 @samp{-d} option. If you are unfortunate enough to work on one of these
14660 systems, you have several alternative ways of printing DVI files:
14661
14662 @itemize @bullet{}
14663 @item Find and install a Unix-like @code{lpr} program, or its clone.
14664 If you can do that, you will be able to print DVI files just like
14665 described above.
14666
14667 @item Send the DVI files to a network printer queue for DVI files.
14668 Some network printers have special queues for printing DVI files. You
14669 should be able to set up your network software to send files to that
14670 queue. In some cases, the version of @code{lpr} which comes with your
14671 network software will have a special option to send a file to specific
14672 queues, like this:
14673
14674 @example
14675 lpr -Qdvi -hprint.server.domain bison.dvi
14676 @end example
14677
14678 @item Convert the DVI file to a Postscript or PCL file and send it to your
14679 local printer. @xref{Invoking Dvips,,, dvips, Dvips}, and the man
14680 pages for @code{dvilj}, for detailed description of these tools. Once
14681 the DVI file is converted to the format your local printer understands
14682 directly, just send it to the appropriate port, usually @samp{PRN}.
14683 @end itemize
14684
14685
14686 @node Within XEmacs
14687 @section From an XEmacs Shell
14688 @cindex Print, format from XEmacs shell
14689 @cindex Format, print from XEmacs shell
14690 @cindex Shell, format, print from
14691 @cindex XEmacs shell, format, print from
14692
14693 You can give formatting and printing commands from a shell within
14694 XEmacs. To create a shell within XEmacs, type @kbd{M-x shell}. In this
14695 shell, you can format and print the document. @xref{Hardcopy, , Format
14696 and Print Hardcopy}, for details.
14697
14698 You can switch to and from the shell buffer while @code{tex} is
14699 running and do other editing. If you are formatting a long document
14700 on a slow machine, this can be very convenient.@refill
14701
14702 You can also use @code{texi2dvi} from an XEmacs shell. For example,
14703 here is how to use @code{texi2dvi} to format and print @cite{Using and
14704 Porting GNU CC} from a shell within XEmacs:
14705
14706 @example
14707 @group
14708 texi2dvi gcc.texinfo
14709 lpr -d gcc.dvi
14710 @end group
14711 @end example
14712
14713 See the next section for more information about formatting
14714 and printing in Texinfo mode.
14715
14716
14717 @node Texinfo Mode Printing
14718 @section Formatting and Printing in Texinfo Mode
14719 @cindex Region printing in Texinfo mode
14720 @cindex Format and print in Texinfo mode
14721 @cindex Print and format in Texinfo mode
14722
14723 Texinfo mode provides several predefined key commands for @TeX{}
14724 formatting and printing. These include commands for sorting indices,
14725 looking at the printer queue, killing the formatting job, and
14726 recentering the display of the buffer in which the operations
14727 occur.@refill
14728
14729 @table @kbd
14730 @item C-c C-t C-b
14731 @itemx M-x texinfo-tex-buffer
14732 Run @code{texi2dvi} on the current buffer.@refill
14733
14734 @item C-c C-t C-r
14735 @itemx M-x texinfo-tex-region
14736 Run @TeX{} on the current region.@refill
14737
14738 @item C-c C-t C-i
14739 @itemx M-x texinfo-texindex
14740 Sort the indices of a Texinfo file formatted with
14741 @code{texinfo-tex-region}.@refill
14742
14743 @item C-c C-t C-p
14744 @itemx M-x texinfo-tex-print
14745 Print a DVI file that was made with @code{texinfo-tex-region} or
14746 @code{texinfo-tex-buffer}.@refill
14747
14748 @item C-c C-t C-q
14749 @itemx M-x tex-show-print-queue
14750 Show the print queue.@refill
14751
14752 @item C-c C-t C-d
14753 @itemx M-x texinfo-delete-from-print-queue
14754 Delete a job from the print queue; you will be prompted for the job
14755 number shown by a preceding @kbd{C-c C-t C-q} command
14756 (@code{texinfo-show-tex-print-queue}).@refill
14757
14758 @item C-c C-t C-k
14759 @itemx M-x tex-kill-job
14760 Kill the currently running @TeX{} job started by either
14761 @code{texinfo-tex-region} or @code{texinfo-tex-buffer}, or any other
14762 process running in the Texinfo shell buffer.@refill
14763
14764 @item C-c C-t C-x
14765 @itemx M-x texinfo-quit-job
14766 Quit a @TeX{} formatting job that has stopped because of an error by
14767 sending an @key{x} to it. When you do this, @TeX{} preserves a record
14768 of what it did in a @file{.log} file.@refill
14769
14770 @item C-c C-t C-l
14771 @itemx M-x tex-recenter-output-buffer
14772 Redisplay the shell buffer in which the @TeX{} printing and formatting
14773 commands are run to show its most recent output.@refill
14774 @end table
14775
14776 @need 1000
14777 Thus, the usual sequence of commands for formatting a buffer is as
14778 follows (with comments to the right):@refill
14779
14780 @example
14781 @group
14782 C-c C-t C-b @r{Run @code{texi2dvi} on the buffer.}
14783 C-c C-t C-p @r{Print the DVI file.}
14784 C-c C-t C-q @r{Display the printer queue.}
14785 @end group
14786 @end example
14787
14788 The Texinfo mode @TeX{} formatting commands start a subshell in XEmacs
14789 called the @file{*tex-shell*}. The @code{texinfo-tex-command},
14790 @code{texinfo-texindex-command}, and @code{tex-dvi-print-command}
14791 commands are all run in this shell.
14792
14793 You can watch the commands operate in the @samp{*tex-shell*} buffer,
14794 and you can switch to and from and use the @samp{*tex-shell*} buffer
14795 as you would any other shell buffer.@refill
14796
14797 @need 1500
14798 The formatting and print commands depend on the values of several variables.
14799 The default values are:@refill
14800
14801 @example
14802 @group
14803 @r{Variable} @r{Default value}
14804
14805 texinfo-texi2dvi-command "texi2dvi"
14806 texinfo-tex-command "tex"
14807 texinfo-texindex-command "texindex"
14808 texinfo-delete-from-print-queue-command "lprm"
14809 texinfo-tex-trailer "@@bye"
14810 tex-start-of-header "%**start"
14811 tex-end-of-header "%**end"
14812 tex-dvi-print-command "lpr -d"
14813 tex-show-queue-command "lpq"
14814 @end group
14815 @end example
14816
14817 You can change the values of these variables with the @kbd{M-x
14818 set-variable} command (@pxref{Examining, , Examining and Setting
14819 Variables, xemacs, XEmacs User's Manual}), or with your @file{init.el}
14820 initialization file (@pxref{Init File, , , xemacs, The XEmacs
14821 Manual}).
14822
14823 @cindex Customize XEmacs package (@t{Development/Docs/Texinfo})
14824 Beginning with version 20, XEmacs offers a user-friendly interface,
14825 called @dfn{Customize}, for changing values of user-definable variables.
14826 @xref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs
14827 User's Manual}, for more details about this. The Texinfo variables can
14828 be found in the @samp{Development/Docs/Texinfo} group, once you invoke
14829 the @kbd{M-x customize} command.
14830
14831
14832 @node Compile-Command
14833 @section Using the Local Variables List
14834 @cindex Local variables
14835 @cindex Compile command for formatting
14836 @cindex Format with the compile command
14837
14838 Yet another way to apply the @TeX{} formatting command to a Texinfo file
14839 is to put that command in a @dfn{local variables list} at the end of the
14840 Texinfo file. You can then specify the @code{tex} or @code{texi2dvi}
14841 commands as a @code{compile-command} and have XEmacs run it by typing
14842 @kbd{M-x compile}. This creates a special shell called the
14843 @file{*compilation*} buffer in which XEmacs runs the compile command.
14844 For example, at the end of the @file{gdb.texinfo} file, after the
14845 @code{@@bye}, you could put the following:@refill
14846
14847 @example
14848 @group
14849 Local Variables:
14850 compile-command: "texi2dvi gdb.texinfo"
14851 End:
14852 @end group
14853 @end example
14854
14855 @noindent
14856 This technique is most often used by programmers who also compile programs
14857 this way; see @ref{Compilation, , , xemacs, XEmacs User's Manual}.@refill
14858
14859
14860 @node Requirements Summary
14861 @section @TeX{} Formatting Requirements Summary
14862 @cindex Requirements for formatting
14863 @cindex Minimal requirements for formatting
14864 @cindex Formatting requirements
14865
14866 Every Texinfo file that is to be input to @TeX{} must begin with a
14867 @code{\input} command and must contain an @code{@@setfilename} command:
14868
14869 @example
14870 \input texinfo
14871 @@setfilename @var{arg-not-used-by-@@TeX@{@}}
14872 @end example
14873
14874 @noindent
14875 The first command instructs @TeX{} to load the macros it needs to
14876 process a Texinfo file and the second command opens auxiliary files.
14877
14878 Every Texinfo file must end with a line that terminates @TeX{}'s
14879 processing and forces out unfinished pages:
14880
14881 @example
14882 @@bye
14883 @end example
14884
14885 Strictly speaking, these lines are all a Texinfo file needs to be
14886 processed successfully by @TeX{}.
14887
14888 Usually, however, the beginning includes an @code{@@settitle} command to
14889 define the title of the printed manual, an @code{@@setchapternewpage}
14890 command, a title page, a copyright page, and permissions. Besides an
14891 @code{@@bye}, the end of a file usually includes indices and a table of
14892 contents. (And of course most manuals contain a body of text as well.)
14893
14894 For more information, see:
14895
14896 @itemize @bullet
14897 @item @ref{settitle, , @code{@@settitle}}.
14898 @item @ref{setchapternewpage, , @code{@@setchapternewpage}}.
14899 @item @ref{Headings, ,Page Headings}.
14900 @item @ref{Titlepage & Copyright Page}.
14901 @item @ref{Printing Indices & Menus}.
14902 @item @ref{Contents}.
14903 @end itemize
14904
14905
14906 @node Preparing for TeX
14907 @section Preparing for @TeX{}
14908 @cindex Preparing for @TeX{}
14909 @cindex @TeX{} input initialization
14910 @cindex @b{.profile} initialization file
14911 @cindex @b{.cshrc} initialization file
14912 @cindex Initialization file for @TeX{} input
14913
14914 @TeX{} needs to know where to find the @file{texinfo.tex} file that the
14915 @samp{\input texinfo} command on the first line reads. The
14916 @file{texinfo.tex} file tells @TeX{} how to handle @@-commands; it is
14917 included in all standard GNU distributions. The latest version is
14918 always available from the Texinfo source repository:
14919 @smalldisplay
14920 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/doc/texinfo.tex?rev=HEAD}
14921 @end smalldisplay
14922
14923 @pindex texinfo.tex@r{, installing}
14924
14925 Usually, the installer has put the @file{texinfo.tex} file in the
14926 default directory that contains @TeX{} macros when GNU Texinfo, XEmacs or
14927 other GNU software is installed. In this case, @TeX{} will find the
14928 file and you do not need to do anything special. If this has not been
14929 done, you can put @file{texinfo.tex} in the current directory when you
14930 run @TeX{}, and @TeX{} will find it there.
14931
14932 @pindex epsf.tex@r{, installing}
14933 Also, you should install @file{epsf.tex}, if it is not already installed
14934 from another distribution. More details are at the end of the description
14935 of the @code{@@image} command (@pxref{Images}).
14936
14937 @cindex European Computer Modern fonts, installing
14938 @cindex EC fonts, installing
14939 @cindex CM-Super fonts, installing
14940 To be able to use quotation marks other than those used in English
14941 you'll need to install European Computer Modern fonts and optionally
14942 CM-Super fonts, unless they are already installed (@pxref{Inserting
14943 Quotation Marks}).
14944
14945 @pindex feymr10@r{, installing}
14946 @cindex Euro font, installing
14947 If you intend to use the @code{@@euro} command, you should install the
14948 Euro font, if it is not already installed. @xref{euro}.
14949
14950 @pindex texinfo.cnf @r{installation}
14951 @cindex Customizing of @TeX{} for Texinfo
14952 @cindex Site-wide Texinfo configuration file
14953 Optionally, you may create an additional @file{texinfo.cnf}, and install
14954 it as well. This file is read by @TeX{} when the @code{@@setfilename}
14955 command is executed (@pxref{setfilename,, @code{@@setfilename}}). You can put any
14956 commands you like there, according to local site-wide conventions. They
14957 will be read by @TeX{} when processing any Texinfo document. For
14958 example, if @file{texinfo.cnf} contains the line @samp{@@afourpaper}
14959 (@pxref{A4 Paper}), then all Texinfo documents will be processed with
14960 that page size in effect. If you have nothing to put in
14961 @file{texinfo.cnf}, you do not need to create it.
14962
14963 @cindex Environment variable @code{TEXINPUTS}
14964 @vindex TEXINPUTS
14965 If neither of the above locations for these system files suffice for
14966 you, you can specify the directories explicitly. For
14967 @file{texinfo.tex}, you can do this by writing the complete path for the
14968 file after the @code{\input} command. Another way, that works for both
14969 @file{texinfo.tex} and @file{texinfo.cnf} (and any other file @TeX{}
14970 might read), is to set the @code{TEXINPUTS} environment variable in your
14971 @file{.cshrc} or @file{.profile} file.
14972
14973 Which you use of @file{.cshrc} or @file{.profile} depends on
14974 whether you use a Bourne shell-compatible (@code{sh}, @code{bash},
14975 @code{ksh}, @dots{}) or C shell-compatible (@code{csh}, @code{tcsh})
14976 command interpreter. The latter read the @file{.cshrc} file for
14977 initialization information, and the former read @file{.profile}.
14978
14979 In a @file{.cshrc} file, you could use the following @code{csh} command
14980 sequence:
14981
14982 @example
14983 setenv TEXINPUTS .:/home/me/mylib:
14984 @end example
14985
14986 @need 1000
14987 In a @file{.profile} file, you could use the following @code{sh} command
14988 sequence:
14989
14990 @example
14991 @group
14992 TEXINPUTS=.:/home/me/mylib:
14993 export TEXINPUTS
14994 @end group
14995 @end example
14996
14997 On MS-DOS/MS-Windows, you would say it like this@footnote{Note the use
14998 of the @samp{;} character, instead of @samp{:}, as directory separator
14999 on these systems.}:
15000
15001 @example
15002 @group
15003 set TEXINPUTS=.;d:/home/me/mylib;c:
15004 @end group
15005 @end example
15006
15007 @noindent
15008 It is customary for DOS/Windows users to put such commands in the
15009 @file{autoexec.bat} file, or in the Windows Registry.
15010
15011 @noindent
15012 These settings would cause @TeX{} to look for @file{\input} file first
15013 in the current directory, indicated by the @samp{.}, then in a
15014 hypothetical user @samp{me}'s @file{mylib} directory, and finally in
15015 the system directories. (A leading, trailing, or doubled @samp{:}
15016 indicates searching the system directories at that point.)
15017
15018 @cindex Dumping a .fmt file
15019 @cindex Format file, dumping
15020 Finally, you may wish to dump a @file{.fmt} file (@pxref{Memory dumps,,,
15021 web2c, Web2c}) so that @TeX{} can load Texinfo faster. (The
15022 disadvantage is that then updating @file{texinfo.tex} requires
15023 redumping.) You can do this by running this command, assuming
15024 @file{epsf.tex} is findable by @TeX{}:
15025
15026 @example
15027 initex texinfo @@dump
15028 @end example
15029
15030 @noindent
15031 (@code{dump} is a @TeX{} primitive.) Then, move @file{texinfo.fmt} to
15032 wherever your @code{.fmt} files are found; typically, this will be in the
15033 subdirectory @file{web2c} of your @TeX{} installation.
15034
15035
15036 @node Overfull hboxes
15037 @section Overfull ``hboxes''
15038 @cindex Overfull @samp{hboxes}
15039 @cindex @samp{hboxes}, overfull
15040 @cindex Final output
15041
15042 @TeX{} is sometimes unable to typeset a line without extending it into
15043 the right margin. This can occur when @TeX{} comes upon what it
15044 interprets as a long word that it cannot hyphenate, such as an
15045 electronic mail network address or a very long title. When this
15046 happens, @TeX{} prints an error message like this:
15047
15048 @example
15049 Overfull @@hbox (20.76302pt too wide)
15050 @end example
15051
15052 @findex hbox
15053 @noindent
15054 (In @TeX{}, lines are in ``horizontal boxes'', hence the term, ``hbox''.
15055 @samp{@@hbox} is a @TeX{} primitive not needed in the Texinfo language.)
15056
15057 @TeX{} also provides the line number in the Texinfo source file and
15058 the text of the offending line, which is marked at all the places that
15059 @TeX{} considered hyphenation.
15060 @xref{Debugging with TeX, , Catching Errors with @TeX{} Formatting},
15061 for more information about typesetting errors.
15062
15063 If the Texinfo file has an overfull hbox, you can rewrite the sentence
15064 so the overfull hbox does not occur, or you can decide to leave it. A
15065 small excursion into the right margin often does not matter and may not
15066 even be noticeable.
15067
15068 If you have many overfull boxes and/or an antipathy to rewriting, you
15069 can coerce @TeX{} into greatly increasing the allowable interword
15070 spacing, thus (if you're lucky) avoiding many of the bad line breaks,
15071 like this:
15072
15073 @findex \emergencystretch
15074 @example
15075 @@tex
15076 \global\emergencystretch = .9\hsize
15077 @@end tex
15078 @end example
15079
15080 @noindent
15081 (You should adjust the fraction as needed.) This huge value for
15082 @code{\emergencystretch} cannot be the default, since then the typeset
15083 output would generally be of noticeably lower quality; the default
15084 is @samp{.15\hsize}. @code{\hsize} is the @TeX{} dimension
15085 containing the current line width.
15086
15087 @cindex Black rectangle in hardcopy
15088 @cindex Rectangle, black in hardcopy
15089 @cindex Box, ugly black in hardcopy
15090 @cindex Ugly black rectangles in hardcopy
15091 For what overfull boxes you have, however, @TeX{} will print a large,
15092 ugly, black rectangle beside the line that contains the overfull hbox
15093 unless told otherwise. This is so you will notice the location of the
15094 problem if you are correcting a draft.
15095
15096 @findex finalout
15097 To prevent such a monstrosity from marring your final printout, write
15098 the following in the beginning of the Texinfo file on a line of its own,
15099 before the @code{@@titlepage} command:
15100
15101 @example
15102 @@finalout
15103 @end example
15104
15105
15106 @node smallbook
15107 @section Printing ``Small'' Books
15108 @findex smallbook
15109 @cindex Small book size
15110 @cindex Book, printing small
15111 @cindex Page sizes for books
15112 @cindex Size of printed book
15113
15114 By default, @TeX{} typesets pages for printing in an 8.5 by 11 inch
15115 format. However, you can direct @TeX{} to typeset a document in a 7 by
15116 9.25 inch format that is suitable for bound books by inserting the
15117 following command on a line by itself at the beginning of the Texinfo
15118 file, before the title page:@refill
15119
15120 @example
15121 @@smallbook
15122 @end example
15123
15124 @noindent
15125 (Since many books are about 7 by 9.25 inches, this command might better
15126 have been called the @code{@@regularbooksize} command, but it came to be
15127 called the @code{@@smallbook} command by comparison to the 8.5 by 11
15128 inch format.)
15129
15130 If you write the @code{@@smallbook} command between the
15131 start-of-header and end-of-header lines, the Texinfo mode @TeX{}
15132 region formatting command, @code{texinfo-tex-region}, will format the
15133 region in ``small'' book size (@pxref{Start of Header}).@refill
15134
15135 @xref{small}, for information about
15136 commands that make it easier to produce examples for a smaller manual.
15137
15138 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
15139 @TeX{}}, for other ways to format with @code{@@smallbook} that do not
15140 require changing the source file.
15141
15142
15143 @node A4 Paper
15144 @section Printing on A4 Paper
15145 @cindex A4 paper, printing on
15146 @cindex A5 paper, printing on
15147 @cindex Paper size, A4
15148 @cindex European A4 paper
15149 @findex afourpaper
15150
15151 You can tell @TeX{} to format a document for printing on European size
15152 A4 paper (or A5) with the @code{@@afourpaper} (or @code{@@afivepaper})
15153 command. Write the command on a line by itself near the beginning of
15154 the Texinfo file, before the title page. For example, this is how you
15155 would write the header for this manual:
15156
15157 @example
15158 @group
15159 \input texinfo @@c -*-texinfo-*-
15160 @@c %**start of header
15161 @@setfilename texinfo
15162 @@settitle Texinfo
15163 @@afourpaper
15164 @@c %**end of header
15165 @end group
15166 @end example
15167
15168 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
15169 @TeX{}}, for other ways to format for different paper sizes that do not
15170 require changing the source file.
15171
15172 @findex afourlatex
15173 @findex afourwide
15174 You may or may not prefer the formatting that results from the command
15175 @code{@@afourlatex}. There's also @code{@@afourwide} for A4 paper in
15176 wide format.
15177
15178 @node pagesizes
15179 @section @code{@@pagesizes} [@var{width}][, @var{height}]: Custom Page Sizes
15180 @findex pagesizes
15181 @cindex Custom page sizes
15182 @cindex Page sizes, customized
15183 @cindex Text width and height
15184 @cindex Width of text area
15185 @cindex Height of text area
15186 @cindex Depth of text area
15187
15188 You can explicitly specify the height and (optionally) width of the main
15189 text area on the page with the @code{@@pagesizes} command. Write this
15190 on a line by itself near the beginning of the Texinfo file, before the
15191 title page. The height comes first, then the width if desired,
15192 separated by a comma. Examples:
15193
15194 @example
15195 @@pagesizes 200mm,150mm @c for b5 paper
15196 @end example
15197 @noindent and
15198 @example
15199 @@pagesizes 11.5in @c for legal paper
15200 @end example
15201
15202 @cindex B5 paper, printing on
15203 @cindex Legal paper, printing on
15204 This would be reasonable for printing on B5-size paper. To emphasize,
15205 this command specifies the size of the @emph{text area}, not the size of
15206 the paper (which is 250@dmn{mm} by 177@dmn{mm} for B5, 14@dmn{in} by
15207 8.5@dmn{in} for legal).
15208
15209 @cindex Margins on page, not controllable
15210 To make more elaborate changes, such as changing any of the page
15211 margins, you must define a new command in @file{texinfo.tex} (or
15212 @file{texinfo.cnf}, @pxref{Preparing for TeX,,Preparing for @TeX{}}).
15213
15214 @xref{Format with texi2dvi}, and @ref{Preparing for TeX,,Preparing for
15215 @TeX{}}, for other ways to specify @code{@@pagesizes} that do not
15216 require changing the source file.
15217
15218 @code{@@pagesizes} is ignored by @code{makeinfo}.
15219
15220
15221 @node Cropmarks and Magnification
15222 @section Cropmarks and Magnification
15223 @findex cropmarks
15224 @cindex Cropmarks for printing
15225 @cindex Printing cropmarks
15226 You can (attempt to) direct @TeX{} to print cropmarks at the corners of
15227 pages with the @code{@@cropmarks} command. Write the @code{@@cropmarks}
15228 command on a line by itself between @code{@@iftex} and @code{@@end
15229 iftex} lines near the beginning of the Texinfo file, before the title
15230 page, like this:@refill
15231
15232 @example
15233 @group
15234 @@iftex
15235 @@cropmarks
15236 @@end iftex
15237 @end group
15238 @end example
15239
15240 This command is mainly for printers that typeset several pages on one
15241 sheet of film; but you can attempt to use it to mark the corners of a
15242 book set to 7 by 9.25 inches with the @code{@@smallbook} command.
15243 (Printers will not produce cropmarks for regular sized output that is
15244 printed on regular sized paper.) Since different printing machines work
15245 in different ways, you should explore the use of this command with a
15246 spirit of adventure. You may have to redefine the command in
15247 @file{texinfo.tex}.
15248
15249 @findex \mag @r{(raw @TeX{} magnification)}
15250 @cindex Magnified printing
15251 @cindex Larger or smaller pages
15252 You can attempt to direct @TeX{} to typeset pages larger or smaller than
15253 usual with the @code{\mag} @TeX{} command. Everything that is typeset
15254 is scaled proportionally larger or smaller. (@code{\mag} stands for
15255 ``magnification''.) This is @emph{not} a Texinfo @@-command, but is a
15256 plain @TeX{} command that is prefixed with a backslash. You have to
15257 write this command between @code{@@tex} and @code{@@end tex}
15258 (@pxref{Raw Formatter Commands}).
15259
15260 Follow the @code{\mag} command with an @samp{=} and then a number that
15261 is 1000 times the magnification you desire. For example, to print pages
15262 at 1.2 normal size, write the following near the beginning of the
15263 Texinfo file, before the title page:
15264
15265 @example
15266 @group
15267 @@tex
15268 \mag=1200
15269 @@end tex
15270 @end group
15271 @end example
15272
15273 With some printing technologies, you can print normal-sized copies that
15274 look better than usual by giving a larger-than-normal master to your
15275 print shop. They do the reduction, thus effectively increasing the
15276 resolution.
15277
15278 Depending on your system, DVI files prepared with a
15279 nonstandard-@code{\mag} may not print or may print only with certain
15280 magnifications. Be prepared to experiment.
15281
15282
15283 @node PDF Output
15284 @section PDF Output
15285 @cindex PDF output
15286
15287 @pindex pdftex
15288 The simplest way to generate PDF output from Texinfo source is to run
15289 the convenience script @command{texi2pdf} (or @command{pdftexi2dvi});
15290 this simply executes the @command{texi2dvi} script with the
15291 @option{--pdf} option (@pxref{Format with texi2dvi}). If for some
15292 reason you want to process the document by hand, simply run the
15293 @command{pdftex} program instead of plain @command{tex}. That is, run
15294 @samp{pdftex foo.texi} instead of @samp{tex foo.texi}.
15295
15296 @dfn{PDF} stands for `Portable Document Format'. It was invented by
15297 Adobe Systems some years ago for document interchange, based on their
15298 PostScript language. Related links:
15299
15300 @itemize
15301 @item
15302 GNU GV, a @uref{http://www.foolabs.com/xpdf/, Ghostscript-based PDF
15303 reader}. (It can also preview PostScript documents.)
15304
15305 @item
15306 A freely available standalone @uref{http://www.foolabs.com/xpdf/,
15307 PDF reader} for the X window system.
15308
15309 @item
15310 @uref{http://partners.adobe.com/asn/acrobat/sdk/public/docs/, PDF definition}.
15311
15312 @end itemize
15313
15314 At present, Texinfo does not provide
15315 @samp{@@ifpdf} or @samp{@@pdf} commands as for the other output
15316 formats, since PDF documents contain many internal links that would be
15317 hard or impossible to get right at the Texinfo source level.
15318
15319 PDF files require special software to be displayed, unlike the plain
15320 ASCII formats (Info, HTML) that Texinfo supports. They also tend to
15321 be much larger than the DVI files output by @TeX{} by default.
15322 Nevertheless, a PDF file does define an actual typeset document in a
15323 self-contained file, so it has its place.
15324
15325
15326 @node Obtaining TeX
15327 @section How to Obtain @TeX{}
15328 @cindex Obtaining @TeX{}
15329 @cindex @TeX{}, how to obtain
15330
15331 @c !!! Here is information about obtaining TeX. Update it whenever.
15332 @c !!! Also consider updating TeX.README on ftp.gnu.org.
15333 @c Updated by RJC on 1 March 1995, conversation with MacKay.
15334 @c Updated by kb@cs.umb.edu on 29 July 1996.
15335 @c Updated by kb@cs.umb.edu on 25 April 1997.
15336 @c Updated by kb@cs.umb.edu on 27 February 1998.
15337 @TeX{} is freely redistributable. You can obtain @TeX{} for Unix
15338 systems via anonymous ftp or on physical media. The core material
15339 consists of the Web2c @TeX{} distribution (@uref{http://tug.org/web2c}).
15340
15341 Instructions for retrieval by anonymous ftp and information on other
15342 available distributions:
15343 @uref{http://tug.org/unixtex.ftp}.
15344
15345 The Free Software Foundation provides a core distribution on its Source
15346 Code CD-ROM suitable for printing Texinfo manuals. To order it, contact:
15347
15348 @display
15349 @group
15350 Free Software Foundation, Inc.
15351 51 Franklin St, Fifth Floor
15352 Boston, MA @ @ 02110-1301
15353 USA
15354 Telephone: @w{+1-617-542-5942}
15355 Fax: (including Japan) @w{+1-617-542-2652}
15356 Free Dial Fax (in Japan):
15357 @w{ } @w{ } @w{ } 0031-13-2473 (KDD)
15358 @w{ } @w{ } @w{ } 0066-3382-0158 (IDC)
15359 Electronic mail: @code{gnu@@gnu.org}
15360 @end group
15361 @end display
15362
15363 Many other @TeX{} distributions are available; see
15364 @uref{http://tug.org/}.
15365
15366
15367 @node Creating and Installing Info Files
15368 @chapter Creating and Installing Info Files
15369
15370 This chapter describes how to create and install Info files. @xref{Info
15371 Files}, for general information about the file format itself.
15372
15373 @menu
15374 * Creating an Info File::
15375 * Installing an Info File::
15376 @end menu
15377
15378
15379 @node Creating an Info File
15380 @section Creating an Info File
15381 @cindex Creating an Info file
15382 @cindex Info, creating an online file
15383 @cindex Formatting a file for Info
15384
15385 @code{makeinfo} is a program that converts a Texinfo file into an Info
15386 file, HTML file, or plain text. @code{texinfo-format-region} and
15387 @code{texinfo-format-buffer} are XEmacs functions that convert
15388 Texinfo to Info.
15389
15390 For information on installing the Info file in the Info system,
15391 @pxref{Installing an Info File}.
15392
15393 @menu
15394 * makeinfo advantages:: @code{makeinfo} provides better error checking.
15395 * Invoking makeinfo:: How to run @code{makeinfo} from a shell.
15396 * makeinfo options:: Specify fill-column and other options.
15397 * Pointer Validation:: How to check that pointers point somewhere.
15398 * makeinfo in XEmacs:: How to run @code{makeinfo} from XEmacs.
15399 * texinfo-format commands:: Two Info formatting commands written
15400 in XEmacs Lisp are an alternative
15401 to @code{makeinfo}.
15402 * Batch Formatting:: How to format for Info in XEmacs Batch mode.
15403 * Tag and Split Files:: How tagged and split files help Info
15404 to run better.
15405 @end menu
15406
15407
15408 @node makeinfo advantages
15409 @subsection @code{makeinfo} Preferred
15410
15411 The @code{makeinfo} utility creates an Info file from a Texinfo source
15412 file more quickly than either of the XEmacs formatting commands and
15413 provides better error messages. We recommend it. @code{makeinfo} is a
15414 C program that is independent of XEmacs. You do not need to run XEmacs to
15415 use @code{makeinfo}, which means you can use @code{makeinfo} on machines
15416 that are too small to run XEmacs. You can run @code{makeinfo} in any one
15417 of three ways: from an operating system shell, from a shell inside
15418 XEmacs, or by typing the @kbd{C-c C-m C-r} or the @kbd{C-c C-m C-b}
15419 command in Texinfo mode in XEmacs.
15420
15421 The @code{texinfo-format-region} and the @code{texinfo-format-buffer}
15422 commands are useful if you cannot run @code{makeinfo}. Also, in some
15423 circumstances, they format short regions or buffers more quickly than
15424 @code{makeinfo}.
15425
15426
15427 @node Invoking makeinfo
15428 @subsection Running @code{makeinfo} from a Shell
15429 @pindex makeinfo
15430
15431 To create an Info file from a Texinfo file, invoke @command{makeinfo}
15432 followed by the name of the Texinfo file. Thus, to create the Info
15433 file for Bison, type the following to the shell:
15434
15435 @example
15436 makeinfo bison.texinfo
15437 @end example
15438
15439 (You can run a shell inside XEmacs by typing @kbd{M-x shell}.)
15440
15441 @command{makeinfo} has many options to control its actions and output;
15442 see the next section.
15443
15444 You can give @command{makeinfo} more than one input file name; each is
15445 processed in turn. If an input file name is @samp{-}, or no input
15446 file names are given at all, standard input is read.
15447
15448
15449 @node makeinfo options
15450 @subsection Options for @code{makeinfo}
15451 @cindex @code{makeinfo} options
15452 @cindex Options for @code{makeinfo}
15453
15454 The @command{makeinfo} program accepts many options. Perhaps the most
15455 commonly needed are those that change the output format. By default,
15456 @command{makeinfo} outputs Info files.
15457
15458 Each command line option is a word preceded by @samp{--} or a letter
15459 preceded by @samp{-}. You can use abbreviations for the long option
15460 names as long as they are unique.
15461
15462 For example, you could use the following shell command to create an Info
15463 file for @file{bison.texinfo} in which each line is filled to only 68
15464 columns:
15465
15466 @example
15467 makeinfo --fill-column=68 bison.texinfo
15468 @end example
15469
15470 You can write two or more options in sequence, like this:@refill
15471
15472 @example
15473 makeinfo --no-split --fill-column=70 @dots{}
15474 @end example
15475
15476 @noindent
15477 This would keep the Info file together as one possibly very long
15478 file and would also set the fill column to 70.
15479
15480 The options are:
15481
15482 @table @code
15483
15484 @item -D @var{var}
15485 @opindex -D @var{var}
15486 Cause the variable @var{var} to be defined. This is equivalent to
15487 @code{@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
15488
15489 @item --commands-in-node-names
15490 @opindex --commands-in-node-names
15491 Allow @code{@@}-commands in node names. This is not recommended, as it
15492 can probably never be implemented in @TeX{}. It also makes
15493 @code{makeinfo} much slower. Also, this option is ignored when
15494 @samp{--no-validate} is used. @xref{Pointer Validation}, for more
15495 details.
15496
15497 @item --css-include=@var{file}
15498 @opindex --css-include
15499 Include the contents of @var{file}, which should contain cascading
15500 style sheets specifications, in the @samp{<style>} block of the HTML
15501 output. @xref{HTML CSS}. If @var{file} is @samp{-}, read standard
15502 input.
15503
15504 @item --css-ref=@var{url}
15505 @opindex --css-ref
15506 In HTML mode, add a @samp{<link>} tag to the HTML output which
15507 references a cascading style sheet at @var{url}. This allows using
15508 standalone style sheets.
15509
15510 @item --disable-encoding
15511 @itemx --enable-encoding
15512 @opindex --disable-encoding
15513 @opindex --enable-encoding
15514 By default, or with @option{--enable-encoding}, output accented and
15515 special characters in Info or plain text output based on
15516 @samp{@@documentencoding}. With @option{--disable-encoding}, 7-bit
15517 ASCII transliterations are output.
15518 @xref{documentencoding,,@code{documentencoding}}, and @ref{Inserting
15519 Accents}.
15520
15521 @item --docbook
15522 @opindex --docbook
15523 Generate Docbook output rather than Info.
15524
15525 @item --document-language=@var{lang}
15526 @opindex --document-language
15527 @vindex LANG
15528 Use @var{lang} to translate Texinfo keywords which end up in the
15529 output document. The default is the locale specified by the
15530 @code{@@documentlanguage} command if there is one
15531 (@pxref{documentlanguage}).
15532
15533 @item --error-limit=@var{limit}
15534 @itemx -e @var{limit}
15535 @opindex --error-limit=@var{limit}
15536 @opindex -e @var{limit}
15537 Set the maximum number of errors that @code{makeinfo} will report
15538 before exiting (on the assumption that continuing would be useless);
15539 default 100.
15540
15541 @item --fill-column=@var{width}
15542 @itemx -f @var{width}
15543 @opindex --fill-column=@var{width}
15544 @opindex -f @var{width}
15545 Specify the maximum number of columns in a line; this is the right-hand
15546 edge of a line. Paragraphs that are filled will be filled to this
15547 width. (Filling is the process of breaking up and connecting lines so
15548 that lines are the same length as or shorter than the number specified
15549 as the fill column. Lines are broken between words.) The default value
15550 is 72. Ignored with @samp{--html}.
15551
15552 @item --footnote-style=@var{style}
15553 @itemx -s @var{style}
15554 @opindex --footnote-style=@var{style}
15555 @opindex -s @var{style}
15556 Set the footnote style to @var{style}, either @samp{end} for the end
15557 node style (the default) or @samp{separate} for the separate node style.
15558 The value set by this option overrides the value set in a Texinfo file
15559 by an @code{@@footnotestyle} command (@pxref{Footnotes}). When the
15560 footnote style is @samp{separate}, @code{makeinfo} makes a new node
15561 containing the footnotes found in the current node. When the footnote
15562 style is @samp{end}, @code{makeinfo} places the footnote references at
15563 the end of the current node. Ignored with @samp{--html}.
15564
15565 @item --force
15566 @itemx -F
15567 @opindex --force
15568 @opindex -F
15569 Ordinarily, if the input file has errors, the output files are not
15570 created. With this option, they are preserved.
15571
15572 @item --help
15573 @itemx -h
15574 @opindex --help
15575 @opindex -h
15576 Print a usage message listing all available options, then exit successfully.
15577
15578 @item --html
15579 @opindex --html
15580 Generate HTML output rather than Info. @xref{Generating HTML}. By
15581 default, the HTML output is split into one output file per Texinfo
15582 source node, and the split output is written into a subdirectory with
15583 the name of the top-level info file.
15584
15585 @item -I @var{dir}
15586 @opindex -I @var{dir}
15587 Append @var{dir} to the directory search list for finding files that
15588 are included using the @code{@@include} command. By default,
15589 @code{makeinfo} searches only the current directory. If @var{dir} is
15590 not given, the current directory @file{.} is appended. Note that
15591 @var{dir} can actually be a list of several directories separated by the
15592 usual path separator character (@samp{:} on Unix, @samp{;} on
15593 MS-DOS/MS-Windows).
15594
15595 @item --ifdocbook
15596 @opindex --ifdocbook
15597 @itemx --ifhtml
15598 @opindex --ifhtml
15599 @itemx --ifinfo
15600 @opindex --ifinfo
15601 @itemx --ifplaintext
15602 @opindex --ifplaintext
15603 @itemx --iftex
15604 @opindex --iftex
15605 @itemx --ifxml
15606 @opindex --ifxml
15607 For the specified format, process @samp{@@if@var{format}} and
15608 @samp{@@@var{format}} commands even if not generating the given output
15609 format. For instance, if @option{--iftex} is specified, then
15610 @samp{@@iftex} and @samp{@@tex} blocks will be read.
15611
15612 @item --internal-links=@var{file}
15613 @opindex --internal-links=@var{file}
15614 In HTML mode, output a tab separated file containing three columns:
15615 the internal link to an indexed item or item in the table of contents,
15616 the name of the index (or "toc") in which it occurs, and the term
15617 which was indexed or entered.
15618
15619 @item --macro-expand=@var{file}
15620 @itemx -E @var{file}
15621 @opindex --macro-expand=@var{file}
15622 @opindex -E @var{file}
15623 Output the Texinfo source with all the macros expanded to the named
15624 file. Normally, the results of macro expansion are used internally by
15625 @code{makeinfo} and then discarded. This option is used by
15626 @command{texi2dvi}.
15627
15628 @item --no-headers
15629 @item --plaintext
15630 @opindex --no-headers
15631 @opindex --plaintext
15632 @cindex Plain text output
15633 @cindex ASCII text output
15634 @cindex Generating plain text files
15635 @cindex @file{INSTALL} file, generating
15636 @cindex Node separators, omitting
15637 @cindex Menus, omitting
15638 Do not include menus or node separator lines in the output, and
15639 implicitly @option{--enable-encoding} (see above). This results in a
15640 simple plain text file that you can (for example) send in email
15641 without complications, or include in a distribution (as in an
15642 @file{INSTALL} file).
15643
15644 @cindex Navigation links, omitting
15645 For HTML output, likewise omit menus. And if @samp{--no-split} is also
15646 specified, do not include a navigation links at the top of each node
15647 (these are never included in the default case of split output).
15648 @xref{Generating HTML}.
15649
15650 In both cases, ignore @code{@@setfilename} and write to standard
15651 output by default---can be overridden with @option{-o}.
15652
15653 @item --no-ifdocbook
15654 @opindex --no-ifdocbook
15655 @itemx --no-ifhtml
15656 @opindex --no-ifhtml
15657 @itemx --no-ifinfo
15658 @opindex --no-ifinfo
15659 @itemx --no-ifplaintext
15660 @opindex --no-ifplaintext
15661 @itemx --no-iftex
15662 @opindex --no-iftex
15663 @itemx --no-ifxml
15664 @opindex --no-ifxml
15665 Do not process @samp{@@if@var{format}} and @samp{@@@var{format}}
15666 commands, and do process @samp{@@ifnot@var{format}}, even if
15667 generating the given format. For instance, if @option{--no-ifhtml} is
15668 specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be
15669 read, and @samp{@@ifnothtml} blocks will be.
15670
15671 @item --no-number-footnotes
15672 @opindex --no-number-footnotes
15673 Suppress automatic footnote numbering. By default, @code{makeinfo}
15674 numbers each footnote sequentially in a single node, resetting the
15675 current footnote number to 1 at the start of each node.
15676
15677 @item --no-number-sections
15678 @opindex --no-number-sections
15679 Do not output chapter, section, and appendix numbers.
15680 You need to specify this if your manual is not hierarchically-structured.
15681
15682 @item --no-split
15683 @opindex --no-split
15684 @cindex Splitting of output files
15685 @cindex Output file splitting
15686 Suppress the splitting stage of @code{makeinfo}. By default, large
15687 output files (where the size is greater than 70k bytes) are split into
15688 smaller subfiles. For Info output, each one is approximately 50k bytes.
15689 For HTML output, each file contains one node (@pxref{Generating HTML}).
15690
15691 @item --no-pointer-validate
15692 @itemx --no-validate
15693 @opindex --no-pointer-validate
15694 @opindex --no-validate
15695 @cindex Pointer validation, suppressing
15696 Suppress the pointer-validation phase of @code{makeinfo}---a dangerous
15697 thing to do. This can also be done with the @code{@@novalidate}
15698 command (@pxref{Use TeX,,Use @TeX{}}). Normally, after a Texinfo file
15699 is processed, some consistency checks are made to ensure that cross
15700 references can be resolved, etc. @xref{Pointer Validation}.
15701
15702 @item --no-warn
15703 @opindex --no-warn
15704 Suppress warning messages (but @emph{not} error messages).
15705
15706 @item --number-sections
15707 @opindex --number-sections
15708 Output chapter, section, and appendix numbers as in printed manuals.
15709 This is the default. It works only with hierarchically-structured
15710 manuals.
15711
15712 @item --output=@var{file}
15713 @itemx -o @var{file}
15714 @opindex --output=@var{file}
15715 @opindex -o @var{file}
15716 Specify that the output should be directed to @var{file} and not to the
15717 file name specified in the @code{@@setfilename} command found in the
15718 Texinfo source (@pxref{setfilename}). If @var{file} is @samp{-}, output
15719 goes to standard output and @samp{--no-split} is implied. For split
15720 HTML output, @var{file} is the name for the directory into which all
15721 HTML nodes are written (@pxref{Generating HTML}).
15722
15723 @item -P @var{dir}
15724 @opindex -P @var{dir}
15725 Prepend @var{dir} to the directory search list for @code{@@include}.
15726 If @var{dir} is not given, the current directory @file{.} is prepended.
15727 See @samp{-I} for more details.
15728
15729 @item --paragraph-indent=@var{indent}
15730 @itemx -p @var{indent}
15731 @opindex --paragraph-indent=@var{indent}
15732 @opindex -p @var{indent}
15733 Set the paragraph indentation style to @var{indent}. The value set by
15734 this option overrides the value set in a Texinfo file by an
15735 @code{@@paragraphindent} command (@pxref{paragraphindent}). The value
15736 of @var{indent} is interpreted as follows:
15737
15738 @table @asis
15739 @item @samp{asis}
15740 Preserve any existing indentation at the starts of paragraphs.
15741
15742 @item @samp{0} or @samp{none}
15743 Delete any existing indentation.
15744
15745 @item @var{num}
15746 Indent each paragraph by @var{num} spaces.
15747 @end table
15748
15749 @item --split-size=@var{num}
15750 @opindex --split-size=@var{num}
15751 Keep Info files to at most @var{num} characters; default is 300,000.
15752
15753 @item --transliterate-file-names
15754 @opindex --transliterate-file-names
15755 Enable transliteration of 8-bit characters in node names for the
15756 purpose of file name creation. @xref{HTML Xref 8-bit Character Expansion}.
15757
15758 @item -U @var{var}
15759 Cause @var{var} to be undefined. This is equivalent to
15760 @code{@@clear @var{var}} in the Texinfo file (@pxref{set clear value}).
15761
15762 @item --verbose
15763 @opindex --verbose
15764 Cause @code{makeinfo} to display messages saying what it is doing.
15765 Normally, @code{makeinfo} only outputs messages if there are errors or
15766 warnings.
15767
15768 @item --version
15769 @itemx -V
15770 @opindex --version
15771 @opindex -V
15772 Print the version number, then exit successfully.
15773
15774 @item --xml
15775 @opindex --xml
15776 Generate XML output rather than Info.
15777
15778 @end table
15779
15780 @vindex TEXINFO_OUTPUT_FORMAT
15781 @cindex Environment variable @code{TEXINFO_OUTPUT_FORMAT}
15782 @command{makeinfo} also reads the environment variable
15783 @env{TEXINFO_OUTPUT_FORMAT} to determine the output format, if not
15784 overridden by a command line option. The possible values are:
15785
15786 @example
15787 docbook html info plaintext xml
15788 @end example
15789
15790 If not set, Info output is the default.
15791
15792
15793 @node Pointer Validation
15794 @subsection Pointer Validation
15795 @cindex Pointer validation with @code{makeinfo}
15796 @cindex Validation of pointers
15797
15798 If you do not suppress pointer validation with the @samp{--no-validate}
15799 option or the @code{@@novalidate} command in the source file (@pxref{Use
15800 TeX,,Use @TeX{}}), @code{makeinfo} will check the validity of the final
15801 Info file. Mostly, this means ensuring that nodes you have referenced
15802 really exist. Here is a complete list of what is checked:
15803
15804 @enumerate
15805 @item
15806 If a `Next', `Previous', or `Up' node reference is a reference to a
15807 node in the current file and is not an external reference such as to
15808 @file{(dir)}, then the referenced node must exist.@refill
15809
15810 @item
15811 In every node, if the `Previous' node is different from the `Up' node,
15812 then the node pointed to by the `Previous' field must have a `Next'
15813 field which points back to this node.@refill
15814
15815 @item
15816 Every node except the `Top' node must have an `Up' pointer.@refill
15817
15818 @item
15819 The node referenced by an `Up' pointer must itself reference the current
15820 node through a menu item, unless the node referenced by `Up'
15821 has the form `(@var{file})'.
15822
15823 @item
15824 If the `Next' reference of a node is not the same as the `Next' reference
15825 of the `Up' reference, then the node referenced by the `Next' pointer
15826 must have a `Previous' pointer that points back to the current node.
15827 This rule allows the last node in a section to point to the first node
15828 of the next chapter.@refill
15829
15830 @item
15831 Every node except `Top' should be referenced by at least one other node,
15832 either via the `Previous' or `Next' links, or via a menu or a
15833 cross-reference.@refill
15834 @end enumerate
15835
15836 @cindex @@-commands in @@node, limited support
15837 Some Texinfo documents might fail during the validation phase because
15838 they use commands like @code{@@value} and @code{@@definfoenclose} in
15839 node definitions and cross-references inconsistently. (Your best bet
15840 is to avoid using @@-commands in node names.) Consider the
15841 following example:
15842
15843 @example
15844 @group
15845 @@set nodename Node 1
15846
15847 @@node @@value@{nodename@}, Node 2, Top, Top
15848
15849 This is node 1.
15850
15851 @@node Node 2, , Node 1, Top
15852
15853 This is node 2.
15854 @end group
15855 @end example
15856
15857 @noindent
15858 Here, the node ``Node 1'' was referenced both verbatim and through
15859 @code{@@value}.
15860
15861 By default, @code{makeinfo} fails such cases, because node names are not
15862 fully expanded until they are written to the output file. You should
15863 always try to reference nodes consistently; e.g., in the above example,
15864 the second @code{@@node} line should have also used @code{@@value}.
15865 However, if, for some reason, you @emph{must} reference node names
15866 inconsistently, and @code{makeinfo} fails to validate the file, you can
15867 use the @samp{--commands-in-node-names} option to force @code{makeinfo}
15868 to perform the expensive expansion of all node names it finds in the
15869 document. This might considerably slow down the program, though;
15870 twofold increase in conversion time was measured for large documents
15871 such as the Jargon file.
15872
15873 @cindex @@value in @@node lines
15874 The support for @code{@@}-commands in @code{@@node} directives is not
15875 general enough to be freely used. For example, if the example above
15876 redefined @code{nodename} somewhere in the document, @code{makeinfo}
15877 will fail to convert it, even if invoked with the
15878 @samp{--commands-in-node-names} option.
15879
15880 @samp{--commands-in-node-names} has no effect if the @samp{--no-validate}
15881 option is given.
15882
15883
15884 @node makeinfo in XEmacs
15885 @subsection Running @code{makeinfo} Within XEmacs
15886 @cindex Running @code{makeinfo} in XEmacs
15887 @cindex @code{makeinfo} inside XEmacs
15888 @cindex Shell, running @code{makeinfo} in
15889
15890 You can run @code{makeinfo} in XEmacs Texinfo mode by using either the
15891 @code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
15892 Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
15893 C-m C-b} by default.@refill
15894
15895 @table @kbd
15896 @item C-c C-m C-r
15897 @itemx M-x makeinfo-region
15898 Format the current region for Info.@refill
15899 @findex makeinfo-region
15900
15901 @item C-c C-m C-b
15902 @itemx M-x makeinfo-buffer
15903 Format the current buffer for Info.@refill
15904 @findex makeinfo-buffer
15905 @end table
15906
15907 When you invoke @code{makeinfo-region} the output goes to a temporary
15908 buffer. When you invoke @code{makeinfo-buffer} output goes to the
15909 file set with @code{@@setfilename} (@pxref{setfilename}).
15910
15911 The XEmacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
15912 run the @code{makeinfo} program in a temporary shell buffer. If
15913 @code{makeinfo} finds any errors, XEmacs displays the error messages in
15914 the temporary buffer.@refill
15915
15916 @cindex Errors, parsing
15917 @cindex Parsing errors
15918 @findex next-error
15919 You can parse the error messages by typing @kbd{C-x `}
15920 (@code{next-error}). This causes XEmacs to go to and position the
15921 cursor on the line in the Texinfo source that @code{makeinfo} thinks
15922 caused the error. @xref{Compilation, , Running @code{make} or
15923 Compilers Generally, xemacs, XEmacs User's Manual}, for more
15924 information about using the @code{next-error} command.@refill
15925
15926 In addition, you can kill the shell in which the @code{makeinfo}
15927 command is running or make the shell buffer display its most recent
15928 output.@refill
15929
15930 @table @kbd
15931 @item C-c C-m C-k
15932 @itemx M-x makeinfo-kill-job
15933 @findex makeinfo-kill-job
15934 Kill the current running @code{makeinfo} job
15935 (from @code{makeinfo-region} or @code{makeinfo-buffer}).@refill
15936
15937 @item C-c C-m C-l
15938 @itemx M-x makeinfo-recenter-output-buffer
15939 @findex makeinfo-recenter-output-buffer
15940 Redisplay the @code{makeinfo} shell buffer to display its most recent
15941 output.@refill
15942 @end table
15943
15944 @noindent
15945 (Note that the parallel commands for killing and recentering a @TeX{}
15946 job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
15947 Printing}.)@refill
15948
15949 You can specify options for @code{makeinfo} by setting the
15950 @code{makeinfo-options} variable with either the @kbd{M-x
15951 customize} or the @kbd{M-x set-variable} command, or by setting the
15952 variable in your @file{init.el} initialization file.
15953
15954 For example, you could write the following in your @file{init.el} file:@refill
15955
15956 @example
15957 @group
15958 (setq makeinfo-options
15959 "--paragraph-indent=0 --no-split
15960 --fill-column=70 --verbose")
15961 @end group
15962 @end example
15963
15964 @noindent
15965 @c If you write these three cross references using xref, you see
15966 @c three references to the same named manual, which looks strange.
15967 @iftex
15968 For more information, see @ref{makeinfo options, , Options for
15969 @code{makeinfo}}, as well as ``Easy Customization Interface,'' ``Examining
15970 and Setting Variables,'' and ``Init File'' in @cite{The XEmacs
15971 Manual}.
15972 @end iftex
15973 @ifnottex
15974 For more information, see@*
15975 @ref{Easy Customization, , Easy Customization Interface, xemacs, XEmacs User's Manual},@*
15976 @ref{Examining, , Examining and Setting Variables, xemacs, XEmacs User's Manual},@*
15977 @ref{Init File, , , xemacs, XEmacs User's Manual}, and@*
15978 @ref{makeinfo options, , Options for @code{makeinfo}}.
15979 @end ifnottex
15980
15981 @node texinfo-format commands
15982 @subsection The @code{texinfo-format@dots{}} Commands
15983
15984 In XEmacs in Texinfo mode, you can format part or all of a Texinfo
15985 file with the @code{texinfo-format-region} command. This formats the
15986 current region and displays the formatted text in a temporary buffer
15987 called @samp{*Info Region*}.@refill
15988
15989 Similarly, you can format a buffer with the
15990 @code{texinfo-format-buffer} command. This command creates a new
15991 buffer and generates the Info file in it. Typing @kbd{C-x C-s} will
15992 save the Info file under the name specified by the
15993 @code{@@setfilename} line which must be near the beginning of the
15994 Texinfo file.@refill
15995
15996 @table @kbd
15997 @item C-c C-e C-r
15998 @itemx @code{texinfo-format-region}
15999 @findex texinfo-format-region
16000 Format the current region for Info.
16001
16002 @item C-c C-e C-b
16003 @itemx @code{texinfo-format-buffer}
16004 @findex texinfo-format-buffer
16005 Format the current buffer for Info.
16006 @end table
16007
16008 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
16009 commands provide you with some error checking, and other functions can
16010 provide you with further help in finding formatting errors. These
16011 procedures are described in an appendix; see @ref{Catching Mistakes}.
16012 However, the @code{makeinfo} program is often faster and
16013 provides better error checking (@pxref{makeinfo in XEmacs}).@refill
16014
16015 @node Batch Formatting
16016 @comment node-name, next, previous, up
16017 @subsection Batch Formatting
16018 @cindex Batch formatting for Info
16019 @cindex Info batch formatting
16020
16021 You can format Texinfo files for Info using @code{batch-texinfo-format}
16022 and XEmacs Batch mode. You can run XEmacs in Batch mode from any shell,
16023 including a shell inside of XEmacs. (@xref{Command Arguments,,,
16024 xemacs, XEmacs User's Manual}.)
16025
16026 Here is a shell command to format all the files that end in
16027 @file{.texinfo} in the current directory:
16028
16029 @example
16030 xemacs -batch -funcall batch-texinfo-format *.texinfo
16031 @end example
16032
16033 @noindent
16034 XEmacs processes all the files listed on the command line, even if an
16035 error occurs while attempting to format some of them.@refill
16036
16037 Run @code{batch-texinfo-format} only with XEmacs in Batch mode as shown;
16038 it is not interactive. It kills the Batch mode XEmacs on completion.@refill
16039
16040 @code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
16041 and want to format several Texinfo files at once. When you use Batch
16042 mode, you create a new XEmacs process. This frees your current XEmacs, so
16043 you can continue working in it. (When you run
16044 @code{texinfo-format-region} or @code{texinfo-format-buffer}, you cannot
16045 use that XEmacs for anything else until the command finishes.)@refill
16046
16047 @node Tag and Split Files
16048 @comment node-name, next, previous, up
16049 @subsection Tag Files and Split Files
16050 @cindex Making a tag table automatically
16051 @cindex Tag table, making automatically
16052
16053 If a Texinfo file has more than 30,000 bytes,
16054 @code{texinfo-format-buffer} automatically creates a tag table
16055 for its Info file; @code{makeinfo} always creates a tag table. With
16056 a @dfn{tag table}, Info can jump to new nodes more quickly than it can
16057 otherwise.@refill
16058
16059 @cindex Indirect subfiles
16060 In addition, if the Texinfo file contains more than about 300,000
16061 bytes, @code{texinfo-format-buffer} and @code{makeinfo} split the
16062 large Info file into shorter @dfn{indirect} subfiles of about 300,000
16063 bytes each. Big files are split into smaller files so that XEmacs does
16064 not need to make a large buffer to hold the whole of a large Info
16065 file; instead, XEmacs allocates just enough memory for the small, split-off
16066 file that is needed at the time. This way, XEmacs avoids wasting
16067 memory when you run Info. (Before splitting was implemented, Info
16068 files were always kept short and @dfn{include files} were designed as
16069 a way to create a single, large printed manual out of the smaller Info
16070 files. @xref{Include Files}, for more information. Include files are
16071 still used for very large documents, such as @cite{The XEmacs Lisp
16072 Reference Manual}, in which each chapter is a separate file.)@refill
16073
16074 When a file is split, Info itself makes use of a shortened version of
16075 the original file that contains just the tag table and references to
16076 the files that were split off. The split-off files are called
16077 @dfn{indirect} files.@refill
16078
16079 The split-off files have names that are created by appending @w{@samp{-1}},
16080 @w{@samp{-2}}, @w{@samp{-3}} and so on to the file name specified by the
16081 @code{@@setfilename} command. The shortened version of the original file
16082 continues to have the name specified by @code{@@setfilename}.@refill
16083
16084 At one stage in writing this document, for example, the Info file was saved
16085 as the file @file{test-texinfo} and that file looked like this:@refill
16086
16087 @example
16088 @group
16089 Info file: test-texinfo, -*-Text-*-
16090 produced by texinfo-format-buffer
16091 from file: new-texinfo-manual.texinfo
16092
16093 ^_
16094 Indirect:
16095 test-texinfo-1: 102
16096 test-texinfo-2: 50422
16097 @end group
16098 @group
16099 test-texinfo-3: 101300
16100 ^_^L
16101 Tag table:
16102 (Indirect)
16103 Node: overview^?104
16104 Node: info file^?1271
16105 @end group
16106 @group
16107 Node: printed manual^?4853
16108 Node: conventions^?6855
16109 @dots{}
16110 @end group
16111 @end example
16112
16113 @noindent
16114 (But @file{test-texinfo} had far more nodes than are shown here.) Each of
16115 the split-off, indirect files, @file{test-texinfo-1},
16116 @file{test-texinfo-2}, and @file{test-texinfo-3}, is listed in this file
16117 after the line that says @samp{Indirect:}. The tag table is listed after
16118 the line that says @samp{Tag table:}. @refill
16119
16120 In the list of indirect files, the number following the file name
16121 records the cumulative number of bytes in the preceding indirect files,
16122 not counting the file list itself, the tag table, or the permissions
16123 text in each file. In the tag table, the number following the node name
16124 records the location of the beginning of the node, in bytes from the
16125 beginning of the (unsplit) output.
16126
16127 If you are using @code{texinfo-format-buffer} to create Info files,
16128 you may want to run the @code{Info-validate} command. (The
16129 @code{makeinfo} command does such a good job on its own, you do not
16130 need @code{Info-validate}.) However, you cannot run the @kbd{M-x
16131 Info-validate} node-checking command on indirect files. For
16132 information on how to prevent files from being split and how to
16133 validate the structure of the nodes, see @ref{Using Info-validate}.
16134
16135
16136 @node Installing an Info File
16137 @section Installing an Info File
16138 @cindex Installing an Info file
16139 @cindex Info file installation
16140 @cindex @file{dir} directory for Info installation
16141
16142 Info files are usually kept in the @file{info} directory. You can read
16143 Info files using the standalone Info program or the Info reader built
16144 into XEmacs. (@inforef{Top, info, info}, for an introduction to Info.)
16145
16146 @menu
16147 * Directory File:: The top level menu for all Info files.
16148 * New Info File:: Listing a new Info file.
16149 * Other Info Directories:: How to specify Info files that are
16150 located in other directories.
16151 * Installing Dir Entries:: How to specify what menu entry to add
16152 to the Info directory.
16153 * Invoking install-info:: @code{install-info} options.
16154 @end menu
16155
16156
16157 @node Directory File
16158 @subsection The Directory File @file{dir}
16159
16160 For Info to work, the @file{info} directory must contain a file that
16161 serves as a top level directory for the Info system. By convention,
16162 this file is called @file{dir}. (You can find the location of this file
16163 within XEmacs by typing @kbd{C-h i} to enter Info and then typing
16164 @kbd{C-x C-f} to see the pathname to the @file{info} directory.)
16165
16166 The @file{dir} file is itself an Info file. It contains the top level
16167 menu for all the Info files in the system. The menu looks like
16168 this:@refill
16169
16170 @example
16171 @group
16172 * Menu:
16173 * Info: (info). Documentation browsing system.
16174 * XEmacs: (xemacs). The extensible, self-documenting
16175 text editor.
16176 * Texinfo: (texinfo). With one source file, make
16177 either a printed manual using
16178 @@TeX@{@} or an Info file.
16179 @dots{}
16180 @end group
16181 @end example
16182
16183 Each of these menu entries points to the `Top' node of the Info file
16184 that is named in parentheses. (The menu entry does not need to
16185 specify the `Top' node, since Info goes to the `Top' node if no node
16186 name is mentioned. @xref{Other Info Files, , Nodes in Other Info
16187 Files}.)@refill
16188
16189 Thus, the @samp{Info} entry points to the `Top' node of the
16190 @file{info} file and the @samp{XEmacs} entry points to the `Top' node
16191 of the @file{xemacs} file.@refill
16192
16193 In each of the Info files, the `Up' pointer of the `Top' node refers
16194 back to the @code{dir} file. For example, the line for the `Top'
16195 node of the XEmacs manual looks like this in Info:@refill
16196
16197 @example
16198 File: xemacs Node: Top, Up: (DIR), Next: Distrib
16199 @end example
16200
16201 @noindent
16202 In this case, the @file{dir} file name is written in upper case
16203 letters---it can be written in either upper or lower case. This is not
16204 true in general, it is a special case for @file{dir}.
16205
16206
16207 @node New Info File
16208 @subsection Listing a New Info File
16209 @cindex Adding a new Info file
16210 @cindex Listing a new Info file
16211 @cindex New Info file, listing it in @file{dir} file
16212 @cindex Info file, listing a new
16213 @cindex @file{dir} file listing
16214
16215 To add a new Info file to your system, you must write a menu entry to
16216 add to the menu in the @file{dir} file in the @file{info} directory.
16217 For example, if you were adding documentation for GDB, you would write
16218 the following new entry:@refill
16219
16220 @example
16221 * GDB: (gdb). The source-level C debugger.
16222 @end example
16223
16224 @noindent
16225 The first part of the menu entry is the menu entry name, followed by a
16226 colon. The second part is the name of the Info file, in parentheses,
16227 followed by a period. The third part is the description.
16228
16229 The name of an Info file often has a @file{.info} extension. Thus, the
16230 Info file for GDB might be called either @file{gdb} or @file{gdb.info}.
16231 The Info reader programs automatically try the file name both with and
16232 without @file{.info}@footnote{On MS-DOS/MS-Windows systems, Info will
16233 try the @file{.inf} extension as well.}; so it is better to avoid
16234 clutter and not to write @samp{.info} explicitly in the menu entry. For
16235 example, the GDB menu entry should use just @samp{gdb} for the file
16236 name, not @samp{gdb.info}.
16237
16238
16239 @node Other Info Directories
16240 @subsection Info Files in Other Directories
16241 @cindex Installing Info in another directory
16242 @cindex Info installed in another directory
16243 @cindex Another Info directory
16244 @cindex @file{dir} files and Info directories
16245
16246 If an Info file is not in the @file{info} directory, there are three
16247 ways to specify its location:@refill
16248
16249 @enumerate
16250 @item
16251 Write the pathname in the @file{dir} file as the second part of the menu.
16252
16253 @item
16254 If you are using XEmacs, list the name of the file in a second @file{dir}
16255 file, in its directory; and then add the name of that directory to the
16256 @code{Info-directory-list} variable in your personal or site
16257 initialization file.
16258
16259 This variable tells XEmacs where to look for @file{dir} files (the files
16260 must be named @file{dir}). XEmacs merges the files named @file{dir} from
16261 each of the listed directories. (In XEmacs version 18, you can set the
16262 @code{Info-directory} variable to the name of only one
16263 directory.)@refill
16264
16265 @item
16266 Specify the Info directory name in the @code{INFOPATH} environment
16267 variable in your @file{.profile} or @file{.cshrc} initialization file.
16268 (Only you and others who set this environment variable will be able to
16269 find Info files whose location is specified this way.)
16270 @end enumerate
16271
16272 For example, to reach a test file in the @file{/home/bob/info}
16273 directory, you could add an entry like this to the menu in the
16274 standard @file{dir} file:@refill
16275
16276 @example
16277 * Test: (/home/bob/info/info-test). Bob's own test file.
16278 @end example
16279
16280 @noindent
16281 In this case, the absolute file name of the @file{info-test} file is
16282 written as the second part of the menu entry.@refill
16283
16284 Alternatively, you could write the following in your @file{init.el} file:
16285
16286 @vindex Info-directory-list
16287 @example
16288 @group
16289 (require 'info)
16290 (setq Info-directory-list
16291 (cons (expand-file-name "/home/bob/info")
16292 Info-directory-list))
16293 @end group
16294 @end example
16295
16296 This tells XEmacs to merge the system @file{dir} file with the @file{dir}
16297 file in @file{/home/bob/info}. Thus, Info will list the
16298 @file{/home/bob/info/info-test} file as a menu entry in the
16299 @file{/home/bob/info/dir} file. XEmacs does the merging only when
16300 @kbd{M-x info} is first run, so if you want to set
16301 @code{Info-directory-list} in an XEmacs session where you've already run
16302 @code{info}, you must @code{(setq Info-dir-contents nil)} to force XEmacs
16303 to recompose the @file{dir} file.
16304
16305 @vindex INFOPATH
16306 @cindex Environment variable @code{INFOPATH}
16307 Finally, you can tell Info where to look by setting the @code{INFOPATH}
16308 environment variable in your shell startup file, such as @file{.cshrc},
16309 @file{.profile} or @file{autoexec.bat}. If you use a Bourne-compatible
16310 shell such as @code{sh} or @code{bash} for your shell command
16311 interpreter, you set the @code{INFOPATH} environment variable in the
16312 @file{.profile} initialization file; but if you use @code{csh} or
16313 @code{tcsh}, you set the variable in the @file{.cshrc} initialization
16314 file. On MS-DOS/MS-Windows systems, you must set @code{INFOPATH} in
16315 your @file{autoexec.bat} file or in the Registry. Each type of shell
16316 uses a different syntax.
16317
16318 @itemize @bullet
16319 @item
16320 In a @file{.cshrc} file, you could set the @code{INFOPATH}
16321 variable as follows:@refill
16322
16323 @smallexample
16324 setenv INFOPATH .:~/info:/usr/local/xemacs/info
16325 @end smallexample
16326
16327 @item
16328 In a @file{.profile} file, you would achieve the same effect by
16329 writing:@refill
16330
16331 @smallexample
16332 INFOPATH=.:$HOME/info:/usr/local/xemacs/info
16333 export INFOPATH
16334 @end smallexample
16335
16336 @item
16337 @pindex autoexec.bat
16338 In a @file{autoexec.bat} file, you write this command@footnote{Note the
16339 use of @samp{;} as the directory separator, and a different syntax for
16340 using values of other environment variables.}:
16341
16342 @smallexample
16343 set INFOPATH=.;%HOME%/info;c:/usr/local/xemacs/info
16344 @end smallexample
16345 @end itemize
16346
16347 @noindent
16348 The @samp{.} indicates the current directory as usual. XEmacs uses the
16349 @code{INFOPATH} environment variable to initialize the value of XEmacs's
16350 own @code{Info-directory-list} variable. The stand-alone Info reader
16351 merges any files named @file{dir} in any directory listed in the
16352 @env{INFOPATH} variable into a single menu presented to you in the node
16353 called @samp{(dir)Top}.
16354
16355 @cindex Colon, last in @env{INFOPATH}
16356 However you set @env{INFOPATH}, if its last character is a
16357 colon@footnote{On MS-DOS/MS-Windows systems, use semi-colon instead.}, this
16358 is replaced by the default (compiled-in) path. This gives you a way to
16359 augment the default path with new directories without having to list all
16360 the standard places. For example (using @code{sh} syntax):
16361
16362 @example
16363 INFOPATH=/local/info:
16364 export INFOPATH
16365 @end example
16366
16367 @noindent
16368 will search @file{/local/info} first, then the standard directories.
16369 Leading or doubled colons are not treated specially.
16370
16371 @cindex @file{dir} file, creating your own
16372 When you create your own @file{dir} file for use with
16373 @code{Info-directory-list} or @env{INFOPATH}, it's easiest to start by
16374 copying an existing @file{dir} file and replace all the text after the
16375 @samp{* Menu:} with your desired entries. That way, the punctuation and
16376 special CTRL-_ characters that Info needs will be present.
16377
16378
16379 @node Installing Dir Entries
16380 @subsection Installing Info Directory Files
16381
16382 When you install an Info file onto your system, you can use the program
16383 @code{install-info} to update the Info directory file @file{dir}.
16384 Normally the makefile for the package runs @code{install-info}, just
16385 after copying the Info file into its proper installed location.
16386
16387 @findex dircategory
16388 @findex direntry
16389 In order for the Info file to work with @code{install-info}, you include
16390 the commands @code{@@dircategory} and
16391 @code{@@direntry}@dots{}@code{@@end direntry} in the Texinfo source
16392 file. Use @code{@@direntry} to specify the menu entries to add to the
16393 Info directory file, and use @code{@@dircategory} to specify which part
16394 of the Info directory to put it in. Here is how these commands are used
16395 in this manual:
16396
16397 @smallexample
16398 @@dircategory Texinfo documentation system
16399 @@direntry
16400 * Texinfo: (texinfo). The GNU documentation format.
16401 * install-info: (texinfo)Invoking install-info. @dots{}
16402 @dots{}
16403 @@end direntry
16404 @end smallexample
16405
16406 Here's what this produces in the Info file:
16407
16408 @smallexample
16409 INFO-DIR-SECTION Texinfo documentation system
16410 START-INFO-DIR-ENTRY
16411 * Texinfo: (texinfo). The GNU documentation format.
16412 * install-info: (texinfo)Invoking install-info. @dots{}
16413 @dots{}
16414 END-INFO-DIR-ENTRY
16415 @end smallexample
16416
16417 @noindent
16418 The @code{install-info} program sees these lines in the Info file, and
16419 that is how it knows what to do.
16420
16421 Always use the @code{@@direntry} and @code{@@dircategory} commands near
16422 the beginning of the Texinfo input, before the first @code{@@node}
16423 command. If you use them later on in the input, @code{install-info}
16424 will not notice them.
16425
16426 @code{install-info} will automatically reformat the description of the
16427 menu entries it is adding. As a matter of convention, the description
16428 of the main entry (above, @samp{The GNU documentation format}) should
16429 start at column 32, starting at zero (as in
16430 @code{what-cursor-position} in XEmacs). This will make it align with
16431 most others. Description for individual utilities best start in
16432 column 48, where possible. For more information about formatting see
16433 the @samp{--calign}, @samp{--align}, and @samp{--max-width} options in
16434 @ref{Invoking install-info}.
16435
16436 If you use @code{@@dircategory} more than once in the Texinfo source,
16437 each usage specifies the `current' category; any subsequent
16438 @code{@@direntry} commands will add to that category.
16439
16440 @cindex Free Software Directory
16441 @cindex Dir categories, choosing
16442 @cindex Categories, choosing
16443 When choosing a category name for the @code{@@dircategory} command, we
16444 recommend consulting the @uref{http://www.gnu.org/directory,
16445 Free Software Directory}. If your program is not listed there,
16446 or listed incorrectly or incompletely, please report the situation to
16447 the directory maintainers (@email{bug-directory@@gnu.org}) so that the
16448 category names can be kept in sync.
16449
16450 Here are a few examples (see the @file{util/dir-example} file in the
16451 Texinfo distribution for large sample @code{dir} file):
16452
16453 @display
16454 XEmacs
16455 Localization
16456 Printing
16457 Software development
16458 Software libraries
16459 Text creation and manipulation
16460 @end display
16461
16462 @cindex Invoking nodes, including in dir file
16463 Each `Invoking' node for every program installed should have a
16464 corresponding @code{@@direntry}. This lets users easily find the
16465 documentation for the different programs they can run, as with the
16466 traditional @command{man} system.
16467
16468
16469 @node Invoking install-info
16470 @subsection Invoking @command{install-info}
16471 @pindex install-info
16472
16473 @code{install-info} inserts menu entries from an Info file into the
16474 top-level @file{dir} file in the Info system (see the previous sections
16475 for an explanation of how the @file{dir} file works). @code{install-info}
16476 also removes menu entries from the @file{dir} file. It's most often
16477 run as part of software installation, or when constructing a @file{dir} file
16478 for all manuals on a system. Synopsis:
16479
16480 @example
16481 install-info [@var{option}]@dots{} [@var{info-file} [@var{dir-file}]]
16482 @end example
16483
16484 If @var{info-file} or @var{dir-file} are not specified, the options
16485 (described below) that define them must be. There are no compile-time
16486 defaults, and standard input is never used. @code{install-info} can
16487 read only one Info file and write only one @file{dir} file per invocation.
16488
16489 @cindex @file{dir}, created by @code{install-info}
16490 If @var{dir-file} (however specified) does not exist,
16491 @code{install-info} creates it if possible (with no entries).
16492
16493 @cindex Compressed dir files, reading
16494 @cindex Bzipped dir files, reading
16495 @cindex LZMA-compressed dir files, reading
16496 @cindex Dir files, compressed
16497 If any input file is compressed with @code{gzip} (@pxref{Top,,,gzip,
16498 Gzip}), @code{install-info} automatically uncompresses it
16499 for reading. And if @var{dir-file} is compressed, @code{install-info}
16500 also automatically leaves it compressed after writing any changes.
16501 If @var{dir-file} itself does not exist, @code{install-info} tries to
16502 open @file{@var{dir-file}.gz}, @file{@var{dir-file}.bz2}, and
16503 @file{@var{dir-file}.lzma}, in that order.
16504
16505 Options:
16506
16507 @table @code
16508 @item --add-once
16509 Specifies that the entry or entries will only be put into a single section.
16510
16511 @item --align=@var{column}
16512 @opindex --align=@var{column}
16513 Specifies the column that the second and subsequent lines of menu entry's
16514 description will be formatted to begin at. The default for this option is
16515 @samp{35}. It is used in conjunction with the @samp{--max-width} option.
16516 @var{column} starts counting at 1.
16517
16518 @item --append-new-sections
16519 Instead of alphabetizing new sections, place them at the end of the DIR file.
16520
16521 @item --calign=@var{column}
16522 @opindex --calign=@var{column}
16523 Specifies the column that the first line of menu entry's description will
16524 be formatted to begin at. The default for this option is @samp{33}. It is
16525 used in conjunction with the @samp{--max-width} option.
16526 When the name of the menu entry exceeds this column, entry's description
16527 will start on the following line.
16528 @var{column} starts counting at 1.
16529
16530 @item --debug
16531 @opindex --debug
16532 Report what is being done.
16533
16534 @item --delete
16535 @opindex --delete
16536 Delete the entries in @var{info-file} from @var{dir-file}. The file
16537 name in the entry in @var{dir-file} must be @var{info-file} (except for
16538 an optional @samp{.info} in either one). Don't insert any new entries.
16539 Any empty sections that result from the removal are also removed.
16540
16541 @item --description=@var{text}
16542 @opindex --description=@var{text}
16543 Specify the explanatory portion of the menu entry. If you don't specify
16544 a description (either via @samp{--entry}, @samp{--item} or this option),
16545 the description is taken from the Info file itself.
16546
16547 @item --dir-file=@var{name}
16548 @opindex --dir-file=@var{name}
16549 Specify file name of the Info directory file. This is equivalent to
16550 using the @var{dir-file} argument.
16551
16552 @item --dry-run
16553 @opindex --dry-run
16554 Same as @samp{--test}.
16555
16556 @item --entry=@var{text}
16557 @opindex --entry=@var{text}
16558 Insert @var{text} as an Info directory entry; @var{text} should have the
16559 form of an Info menu item line plus zero or more extra lines starting
16560 with whitespace. If you specify more than one entry, they are all
16561 added. If you don't specify any entries, they are determined from
16562 information in the Info file itself.
16563
16564 @item --help
16565 @opindex --help
16566 Display a usage message with basic usage and all available options,
16567 then exit successfully.
16568
16569 @item --info-file=@var{file}
16570 @opindex --info-file=@var{file}
16571 Specify Info file to install in the directory. This is
16572 equivalent to using the @var{info-file} argument.
16573
16574 @item --info-dir=@var{dir}
16575 @opindex --info-dir=@var{dir}
16576 Specify the directory where the directory file @file{dir} resides.
16577 Equivalent to @samp{--dir-file=@var{dir}/dir}.
16578
16579 @item --infodir=@var{dir}
16580 @opindex --infodir=@var{dir}
16581 Same as @samp{--info-dir}.
16582
16583 @item --item=@var{text}
16584 @opindex --item=@var{text}
16585 Same as @samp{--entry=@var{text}}. An Info directory entry is actually
16586 a menu item.
16587
16588 @item --keep-old
16589 @opindex --keep-old
16590 Do not replace pre-existing menu entries. When @samp{--remove} is specified,
16591 this option means that empty sections are not removed.
16592
16593 @item --max-width=@var{column}
16594 @opindex --max-width=@var{column}
16595 Specifies the column that the menu entry's description will be word-wrapped
16596 at. @var{column} starts counting at 1.
16597
16598 @item --maxwidth=@var{column}
16599 @opindex --maxwidth=@var{column}
16600 Same as @samp{--max-width}.
16601
16602 @item --menuentry=@var{text}
16603 @opindex --menuentry=@var{text}
16604 Same as @samp{--name}.
16605
16606 @item --name=@var{text}
16607 @opindex --name=@var{text}
16608 Specify the name portion of the menu entry. If the @var{text} does
16609 not start with an asterisk @samp{*}, it is presumed to be the text
16610 after the @samp{*} and before the parentheses that specify the Info
16611 file. Otherwise @var{text} is taken verbatim, and is taken as
16612 defining the text up to and including the first period (a space is
16613 appended if necessary). If you don't specify the name (either via
16614 @samp{--entry}, @samp{--item} or this option), it is taken from the
16615 Info file itself. If the Info does not contain the name, the basename
16616 of the Info file is used.
16617
16618 @item --no-indent
16619 @opindex --no-indent
16620 Suppress formatting of new entries into the @file{dir} file.
16621
16622 @item --quiet
16623 @opindex --quiet
16624 @itemx --silent
16625 @opindex --silent
16626 Suppress warnings, etc., for silent operation.
16627
16628 @item --remove
16629 @opindex --remove
16630 Same as @samp{--delete}.
16631
16632 @item --remove-exactly
16633 @opindex --remove-exactly
16634 Also like @samp{--delete}, but only entries if the Info file name
16635 matches exactly; @code{.info} and/or @code{.gz} suffixes are
16636 @emph{not} ignored.
16637
16638 @item --section=@var{sec}
16639 @opindex --section=@var{sec}
16640 Put this file's entries in section @var{sec} of the directory. If you
16641 specify more than one section, all the entries are added in each of the
16642 sections. If you don't specify any sections, they are determined from
16643 information in the Info file itself. If the Info file doesn't specify
16644 a section, the menu entries are put into the Miscellaneous section.
16645
16646 @item --section @var{regex} @var{sec}
16647 @opindex --section @var{regex} @var{sec}
16648 Same as @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
16649
16650 @code{install-info} tries to detect when this alternate syntax is used,
16651 but does not always guess correctly. Here is the heuristic that
16652 @code{install-info} uses:
16653 @enumerate
16654 @item
16655 If the second argument to @code{--section} starts with a hyphen, the
16656 original syntax is presumed.
16657 @item
16658 If the second argument to @code{--section} is a file that can be
16659 opened, the original syntax is presumed.
16660 @item
16661 Otherwise the alternate syntax is used.
16662 @end enumerate
16663
16664 When heuristic fails because your section title starts with a hyphen, or it
16665 happens to be a filename that can be opened, the syntax should be changed
16666 to @samp{--regex=@var{regex} --section=@var{sec} --add-once}.
16667
16668
16669 @item --regex=@var{regex}
16670 @opindex --regex=@var{regex}
16671 Put this file's entries into any section that matches @var{regex}. If
16672 more than one section matches, all of the entries are added in each of the
16673 sections. Specify @var{regex} using basic regular expression syntax, more
16674 or less as used with @command{grep}, for example.
16675
16676 @item --test
16677 @opindex --test
16678 Suppress updating of the directory file.
16679
16680 @item --version
16681 @opindex --version
16682 @cindex Version number, for install-info
16683 Display version information and exit successfully.
16684
16685 @end table
16686
16687
16688 @node Generating HTML
16689 @chapter Generating HTML
16690 @cindex HTML output
16691
16692 @command{makeinfo} generates Info output by default, but given the
16693 @option{--html} option, it will generate HTML, for web browsers and
16694 other programs. This chapter gives some details on such HTML output.
16695
16696
16697 @command{makeinfo} can also write in XML and Docbook format, but we do
16698 not as yet describe these further. @xref{Output Formats}, for a brief
16699 overview of all the output formats.
16700
16701 @menu
16702 * HTML Translation:: Details of the HTML output.
16703 * HTML Splitting:: How HTML output is split.
16704 * HTML CSS:: Influencing HTML output with Cascading Style Sheets.
16705 * HTML Xref:: Cross-references in HTML output.
16706 @end menu
16707
16708
16709 @node HTML Translation
16710 @section HTML Translation
16711
16712 @command{makeinfo} will include segments of Texinfo source between
16713 @code{@@ifhtml} and @code{@@end ifhtml} in the HTML output (but not
16714 any of the other conditionals, by default). Source between
16715 @code{@@html} and @code{@@end html} is passed without change to the
16716 output (i.e., suppressing the normal escaping of input @samp{<},
16717 @samp{>} and @samp{&} characters which have special significance in
16718 HTML). @xref{Conditional Commands}.
16719
16720 @opindex --footnote-style@r{, ignored in HTML output}
16721 The @option{--footnote-style} option is currently ignored for HTML output;
16722 footnotes are always linked to the end of the output file.
16723
16724 @cindex Navigation bar, in HTML output
16725 By default, a navigation bar is inserted at the start of each node,
16726 analogous to Info output. The @samp{--no-headers} option suppresses
16727 this if used with @samp{--no-split}. Header @code{<link>} elements in
16728 split output can support info-like navigation with browsers like Lynx
16729 and @w{Emacs W3} which implement this HTML@tie{}1.0 feature.
16730
16731 @cindex HTML output, browser compatibility of
16732 The HTML generated is mostly standard (i.e., HTML@tie{}2.0, RFC-1866).
16733 One exception is that HTML@tie{}3.2 tables are generated from the
16734 @code{@@multitable} command, but tagged to degrade as well as possible
16735 in browsers without table support. The HTML@tie{}4 @samp{lang}
16736 attribute on the @samp{<html>} attribute is also used. (Please report
16737 output from an error-free run of @code{makeinfo} which has browser
16738 portability problems as a bug.)
16739
16740
16741 @node HTML Splitting
16742 @section HTML Splitting
16743 @cindex Split HTML output
16744 @cindex HTML output, split
16745
16746 When splitting output (which is the default), @command{makeinfo}
16747 writes HTML output into (generally) one output file per Texinfo source
16748 @code{@@node}.
16749
16750 The output file name is the node name with special characters replaced
16751 by @samp{-}'s, so it can work as a filename. In the unusual case of
16752 two different nodes having the same name after this treatment, they
16753 are written consecutively to the same file, with HTML anchors so each
16754 can be referred to separately. If @command{makeinfo} is run on a
16755 system which does not distinguish case in filenames, nodes which are
16756 the same except for case will also be folded into the same output
16757 file.
16758
16759 When splitting, the HTML output files are written into a subdirectory,
16760 with the name chosen as follows:
16761 @enumerate
16762 @item
16763 @command{makeinfo} first tries the subdirectory with the base name
16764 from @code{@@setfilename} (that is, any extension is removed). For
16765 example, HTML output for @code{@@setfilename gcc.info} would be
16766 written into a subdirectory named @samp{gcc}.
16767
16768 @item
16769 If that directory cannot be created for any reason, then
16770 @command{makeinfo} tries appending @samp{.html} to the directory name.
16771 For example, output for @code{@@setfilename texinfo} would be written
16772 to @samp{texinfo.html}.
16773
16774 @item
16775 If the @samp{@var{name}.html} directory can't be
16776 created either, @code{makeinfo} gives up.
16777
16778 @end enumerate
16779
16780 @noindent In any case, the top-level output file within the directory
16781 is always named @samp{index.html}.
16782
16783 Monolithic output (@code{--no-split}) is named according to
16784 @code{@@setfilename} (with any @samp{.info} extension is replaced with
16785 @samp{.html}) or @code{--output} (the argument is used literally).
16786
16787
16788 @node HTML CSS
16789 @section HTML CSS
16790 @cindex HTML, and CSS
16791 @cindex CSS, and HTML output
16792 @cindex Cascading Style Sheets, and HTML output
16793
16794 Cascading Style Sheets (CSS for short) is an Internet standard for
16795 influencing the display of HTML documents: see
16796 @uref{http://www.w3.org/Style/CSS/}.
16797
16798 By default, @command{makeinfo} includes a few simple CSS commands to
16799 better implement the appearance of some of the environments. Here
16800 are two of them, as an example:
16801
16802 @example
16803 pre.display @{ font-family:inherit @}
16804 pre.smalldisplay @{ font-family:inherit; font-size:smaller @}
16805 @end example
16806
16807 A full explanation of CSS is (far) beyond this manual; please see the
16808 reference above. In brief, however, this specification tells the web
16809 browser to use a `smaller' font size for @code{@@smalldisplay} text,
16810 and to use the `inherited' font (generally a regular roman typeface)
16811 for both @code{@@smalldisplay} and @code{@@display}. By default, the
16812 HTML @samp{<pre>} command uses a monospaced font.
16813
16814 You can influence the CSS in the HTML output with two
16815 @command{makeinfo} options: @option{--css-include=@var{file}} and
16816 @option{--css-ref=@var{url}}.
16817
16818 The option @option{--css-ref=@var{url}} adds to each output HTML file
16819 a @samp{<link>} tag referencing a CSS at the given @var{url}. This
16820 allows using external style sheets.
16821
16822 The option @option{--css-include=@var{file}} includes the contents
16823 @var{file} in the HTML output, as you might expect. However, the
16824 details are somewhat tricky, as described in the following, to provide
16825 maximum flexibility.
16826
16827 @cindex @@import specifications, in CSS files
16828 The CSS file may begin with so-called @samp{@@import} directives,
16829 which link to external CSS specifications for browsers to use when
16830 interpreting the document. Again, a full description is beyond our
16831 scope here, but we'll describe how they work syntactically, so we can
16832 explain how @command{makeinfo} handles them.
16833
16834 @cindex Comments, in CSS files
16835 There can be more than one @samp{@@import}, but they have to come
16836 first in the file, with only whitespace and comments interspersed, no
16837 normal definitions. (Technical exception: an @samp{@@charset}
16838 directive may precede the @samp{@@import}'s. This does not alter
16839 @command{makeinfo}'s behavior, it just copies the @samp{@@charset} if
16840 present.) Comments in CSS files are delimited by @samp{/* ... */}, as
16841 in C. An @samp{@@import} directive must be in one of these two forms:
16842
16843 @example
16844 @@import url(http://example.org/foo.css);
16845 @@import "http://example.net/bar.css";
16846 @end example
16847
16848 As far as @command{makeinfo} is concerned, the crucial characters are
16849 the @samp{@@} at the beginning and the semicolon terminating the
16850 directive. When reading the CSS file, it simply copies any such
16851 @samp{@@}-directive into the output, as follows:
16852
16853 @itemize
16854 @item If @var{file} contains only normal CSS declarations, it is
16855 included after @command{makeinfo}'s default CSS, thus overriding it.
16856
16857 @item If @var{file} begins with @samp{@@import} specifications (see
16858 below), then the @samp{import}'s are included first (they have to come
16859 first, according to the standard), and then @command{makeinfo}'s
16860 default CSS is included. If you need to override @command{makeinfo}'s
16861 defaults from an @samp{@@import}, you can do so with the @samp{!@:
16862 important} CSS construct, as in:
16863 @example
16864 pre.smallexample @{ font-size: inherit ! important @}
16865 @end example
16866
16867 @item If @var{file} contains both @samp{@@import} and inline CSS
16868 specifications, the @samp{@@import}'s are included first, then
16869 @command{makeinfo}'s defaults, and lastly the inline CSS from
16870 @var{file}.
16871
16872 @item Any @@-directive other than @samp{@@import} and @samp{@@charset}
16873 is treated as a CSS declaration, meaning @command{makeinfo} includes
16874 its default CSS and then the rest of the file.
16875
16876 @end itemize
16877
16878 If the CSS file is malformed or erroneous, @command{makeinfo}'s output
16879 is unspecified. @command{makeinfo} does not try to interpret the
16880 meaning of the CSS file in any way; it just looks for the special
16881 @samp{@@} and @samp{;} characters and blindly copies the text into the
16882 output. Comments in the CSS file may or may not be included in the
16883 output.
16884
16885
16886 @node HTML Xref
16887 @section HTML Cross-references
16888 @cindex HTML cross-references
16889 @cindex Cross-references, in HTML output
16890
16891 Cross-references between Texinfo manuals in HTML format amount, in the
16892 end, to a standard HTML @code{<a>} link, but the details are
16893 unfortunately complex. This section describes the algorithm used in
16894 detail, so that Texinfo can cooperate with other programs, such as
16895 @command{texi2html}, by writing mutually compatible HTML files.
16896
16897 This algorithm may or may not be used for links @emph{within} HTML
16898 output for a Texinfo file. Since no issues of compatibility arise in
16899 such cases, we do not need to specify this.
16900
16901 We try to support references to such ``external'' manuals in both
16902 monolithic and split forms. A @dfn{monolithic} (mono) manual is
16903 entirely contained in one file, and a @dfn{split} manual has a file
16904 for each node. (@xref{HTML Splitting}.)
16905
16906 @cindex Dumas, Patrice
16907 Acknowledgement: this algorithm was primarily devised by Patrice Dumas
16908 in 2003--04.
16909
16910 @menu
16911 * Link Basics: HTML Xref Link Basics.
16912 * Node Expansion: HTML Xref Node Name Expansion.
16913 * Command Expansion: HTML Xref Command Expansion.
16914 * 8-bit Expansion: HTML Xref 8-bit Character Expansion.
16915 * Mismatch: HTML Xref Mismatch.
16916 @end menu
16917
16918
16919 @node HTML Xref Link Basics
16920 @subsection HTML Cross-reference Link Basics
16921 @cindex HTML cross-reference link basics
16922
16923 For our purposes, an HTML link consists of four components: a host
16924 name, a directory part, a file part, and a target part. We
16925 always assume the @code{http} protocol. For example:
16926
16927 @example
16928 http://@var{host}/@var{dir}/@var{file}.html#@var{target}
16929 @end example
16930
16931 The information to construct a link comes from the node name and
16932 manual name in the cross-reference command in the Texinfo source
16933 (@pxref{Cross References}), and from @dfn{external information}, which
16934 is currently simply hardwired. In the future, it may come from an
16935 external data file.
16936
16937 We now consider each part in turn.
16938
16939 The @var{host} is hardwired to be the local host. This could either
16940 be the literal string @samp{localhost}, or, according to the rules for
16941 HTML links, the @samp{http://localhost/} could be omitted entirely.
16942
16943 The @var{dir} and @var{file} parts are more complicated, and depend on
16944 the relative split/mono nature of both the manual being processed and
16945 the manual that the cross-reference refers to. The underlying idea is
16946 that there is one directory for Texinfo manuals in HTML, and a given
16947 @var{manual} is either available as a monolithic file
16948 @file{@var{manual}.html}, or a split subdirectory
16949 @file{@var{manual}/*.html}. Here are the cases:
16950
16951 @itemize @bullet
16952 @item
16953 If the present manual is split, and the referent manual is also split,
16954 the directory is @samp{../@var{referent/}} and the file is the
16955 expanded node name (described later).
16956
16957 @item
16958 If the present manual is split, and the referent manual is mono, the
16959 directory is @samp{../} and the file is @file{@var{referent}.html}.
16960
16961 @item
16962 If the present manual is mono, and the referent manual is split, the
16963 directory is @file{@var{referent}/} and the file is the expanded node
16964 name.
16965
16966 @item
16967 If the present manual is mono, and the referent manual is also mono,
16968 the directory is @file{./} (or just the empty string), and the file is
16969 @file{@var{referent}.html}.
16970
16971 @end itemize
16972
16973 One exception: the algorithm for node name expansion prefixes the
16974 string @samp{g_t} when the node name begins with a non-letter. This
16975 kludge (due to XHTML rules) is not necessary for filenames, and is
16976 therefore omitted.
16977
16978 Any directory part in the filename argument of the source
16979 cross-reference command is ignored. Thus, @code{@@xref@{,,,../foo@}}
16980 and @code{@@xref@{,,,foo@}} both use @samp{foo} as the manual name.
16981 This is because any such attempted hardwiring of the directory is very
16982 unlikely to be useful for both Info and HTML output.
16983
16984 Finally, the @var{target} part is always the expanded node name.
16985
16986 Whether the present manual is split or mono is determined by user
16987 option; @command{makeinfo} defaults to split, with the
16988 @option{--no-split} option overriding this.
16989
16990 Whether the referent manual is split or mono is another bit of the
16991 external information. For now, @command{makeinfo} simply assumes the
16992 referent manual is the same as the present manual.
16993
16994 There can be a mismatch between the format of the referent manual that
16995 the generating software assumes, and the format it's actually present
16996 in. @xref{HTML Xref Mismatch}.
16997
16998
16999 @node HTML Xref Node Name Expansion
17000 @subsection HTML Cross-reference Node Name Expansion
17001 @cindex HTML cross-reference node name expansion
17002 @cindex node name expansion, in HTML cross-references
17003 @cindex expansion, of node names in HTML cross-references
17004
17005 As mentioned in the previous section, the key part of the HTML
17006 cross-reference algorithm is the conversion of node names in the
17007 Texinfo source into strings suitable for XHTML identifiers and
17008 filenames. The restrictions are similar for each: plain ASCII
17009 letters, numbers, and the @samp{-} and @samp{_} characters are all
17010 that can be used. (Although HTML anchors can contain most characters,
17011 XHTML is more restrictive.)
17012
17013 Cross-references in Texinfo can actually refer either to nodes or
17014 anchors (@pxref{anchor}), but anchors are treated identically to nodes
17015 in this context, so we'll continue to say ``node'' names for
17016 simplicity.
17017
17018 (@@-commands and 8-bit characters are not presently handled by
17019 @command{makeinfo} for HTML cross-references. See the next section.)
17020
17021 A special exception: the Top node (@pxref{The Top Node}) is always
17022 mapped to the file @file{index.html}, to match web server software.
17023 However, the HTML @emph{target} is @samp{Top}. Thus (in the split case):
17024
17025 @example
17026 @@xref@{Top, Introduction,, xemacs, XEmacs User's Manual@}.
17027 @result{} <a href="xemacs/index.html#Top">
17028 @end example
17029
17030 @enumerate
17031 @item
17032 The standard ASCII letters (a-z and A-Z) are not modified. All other
17033 characters are changed as specified below.
17034
17035 @item
17036 The standard ASCII numbers (0-9) are not modified except when a number
17037 is the first character of the node name. In that case, see below.
17038
17039 @item
17040 Multiple consecutive space, tab and newline characters are transformed
17041 into just one space. (It's not possible to have newlines in node
17042 names with the current implementation, but we specify it anyway, just
17043 in case.)
17044
17045 @item
17046 Leading and trailing spaces are removed.
17047
17048 @item
17049 After the above has been applied, each remaining space character is
17050 converted into a @samp{-} character.
17051
17052 @item
17053 Other ASCII 7-bit characters are transformed into @samp{_00@var{xx}},
17054 where @var{xx} is the ASCII character code in (lowercase) hexadecimal.
17055 This includes @samp{_}, which is mapped to @samp{_005f}.
17056
17057 @item
17058 If the node name does not begin with a letter, the literal string
17059 @samp{g_t} is prefixed to the result. (Due to the rules above, that
17060 string can never occur otherwise; it is an arbitrary choice, standing
17061 for ``GNU Texinfo''.) This is necessary because XHTML requires that
17062 identifiers begin with a letter.
17063
17064 @end enumerate
17065
17066 For example:
17067
17068 @example
17069 @@node A node --- with _'%
17070 @result{} A-node-_002d_002d_002d-with-_005f_0027_0025
17071 @end example
17072
17073 Notice in particular:
17074
17075 @itemize @bullet
17076 @item @samp{_} @result{} @samp{_005f}
17077 @item @samp{-} @result{} @samp{_002d}
17078 @item @samp{A node} @result{} @samp{A-node}
17079 @end itemize
17080
17081 On case-folding computer systems, nodes differing only by case will be
17082 mapped to the same file.
17083
17084 In particular, as mentioned above, Top always maps to the file
17085 @file{index.html}. Thus, on a case-folding system, Top and a node
17086 named `Index' will both be written to @file{index.html}.
17087
17088 Fortunately, the targets serve to distinguish these cases, since HTML
17089 target names are always case-sensitive, independent of operating
17090 system.
17091
17092
17093 @node HTML Xref Command Expansion
17094 @subsection HTML Cross-reference Command Expansion
17095 @cindex HTML cross-reference command expansion
17096
17097 In standard Texinfo, node names may not contain @@-commands.
17098 @command{makeinfo} has an option @option{--commands-in-node-names}
17099 which partially supports it (@pxref{Invoking makeinfo}), but it is not
17100 robust and not recommended.
17101
17102 Thus, @command{makeinfo} does not fully implement this part of the
17103 HTML cross-reference algorithm, but it is documented here for the sake
17104 of completeness.
17105
17106 First, comments are removed.
17107
17108 Next, any @code{@@value} commands (@pxref{set value}) and macro invocations
17109 (@pxref{Invoking Macros}) are fully expanded.
17110
17111 Then, for the following commands, the command name and braces are removed,
17112 the text of the argument is recursively transformed:
17113 @example
17114 @@asis @@b @@cite @@code @@command @@dfn @@dmn @@dotless
17115 @@emph @@env @@file @@indicateurl @@kbd @@key
17116 @@samp @@sc @@slanted @@strong @@t @@var @@w
17117 @end example
17118
17119 @noindent For @code{@@sc}, any letters are capitalized.
17120
17121 The following commands are replaced by constant text, as shown. If
17122 any of these commands have non-empty arguments, as in
17123 @code{@@TeX@{bad@}}, it is an error, and the result is unspecified.
17124 `(space)' means a space character, `(nothing)' means the empty string,
17125 etc. The notation `U+@var{xxxx}' means Unicode code point @var{xxxx}
17126 (in hex, as usual). There are further transformations of many of
17127 these expansions for the final file or target name, such as space
17128 characters to @samp{-}, etc., according to the other rules.
17129
17130 @multitable @columnfractions .3 .5
17131 @item @code{@@(newline)} @tab (space)
17132 @item @code{@@(space)} @tab (space)
17133 @item @code{@@(tab)} @tab (space)
17134 @item @code{@@!} @tab @samp{!}
17135 @item @code{@@*} @tab (space)
17136 @item @code{@@-} @tab (nothing)
17137 @item @code{@@.} @tab @samp{.}
17138 @item @code{@@:} @tab (nothing)
17139 @item @code{@@?} @tab @samp{?}
17140 @item @code{@@@@} @tab @samp{@@}
17141 @item @code{@@@{} @tab @samp{@{}
17142 @item @code{@@@}} @tab @samp{@}}
17143 @item @code{@@LaTeX} @tab @samp{LaTeX}
17144 @item @code{@@TeX} @tab @samp{TeX}
17145 @item @code{@@arrow} @tab U+2192
17146 @item @code{@@bullet} @tab U+2022
17147 @item @code{@@comma} @tab @samp{,}
17148 @item @code{@@copyright} @tab U+00A9
17149 @item @code{@@dots} @tab U+2026
17150 @item @code{@@enddots} @tab @samp{...}
17151 @item @code{@@equiv} @tab U+2261
17152 @item @code{@@error} @tab @samp{error-->}
17153 @item @code{@@euro} @tab U+20AC
17154 @item @code{@@exclamdown} @tab U+00A1
17155 @item @code{@@expansion} @tab U+2192
17156 @item @code{@@geq} @tab U+2265
17157 @item @code{@@leq} @tab U+2264
17158 @item @code{@@minus} @tab U+2212
17159 @item @code{@@ordf} @tab U+00AA
17160 @item @code{@@ordm} @tab U+00BA
17161 @item @code{@@point} @tab U+2605
17162 @item @code{@@pounds} @tab U+00A3
17163 @item @code{@@print} @tab U+22A3
17164 @item @code{@@questiondown} @tab U+00BF
17165 @item @code{@@registeredsymbol} @tab U+00AE
17166 @item @code{@@result} @tab U+21D2
17167 @item @code{@@textdegree} @tab U+00B0
17168 @item @code{@@tie} @tab (space)
17169 @end multitable
17170
17171 Quotation mark commands are likewise replaced by their Unicode values
17172 (@pxref{Inserting Quotation Marks}).
17173
17174 An @code{@@acronym} or @code{@@abbr} command is replaced by the first
17175 argument, followed by the second argument in parentheses, if present.
17176 @xref{acronym}.
17177
17178 An @code{@@email} command is replaced by the @var{text} argument if
17179 present, else the address. @xref{email}.
17180
17181 An @code{@@image} command is replaced by the filename (first)
17182 argument. @xref{Images}.
17183
17184 A @code{@@verb} command is replaced by its transformed argument.
17185 @xref{verb}.
17186
17187 Any other command is an error, and the result is unspecified.
17188
17189
17190 @node HTML Xref 8-bit Character Expansion
17191 @subsection HTML Cross-reference 8-bit Character Expansion
17192 @cindex HTML cross-reference 8-bit character expansion
17193 @cindex 8-bit characters, in HTML cross-references
17194 @cindex Expansion of 8-bit characters in HTML cross-references
17195 @cindex Transliteration of 8-bit characters in HTML cross-references
17196
17197 Usually, characters other than plain 7-bit ASCII are transformed into
17198 the corresponding Unicode code point(s) in Normalization Form C, which
17199 uses precomposed characters where available. (This is the
17200 normalization form recommended by the W3C and other bodies.) This
17201 holds when that code point is 0xffff or less, as it almost always is.
17202
17203 These will then be further transformed by the rules above into the
17204 string @samp{_@var{xxxx}}, where @var{xxxx} is the code point in hex.
17205
17206 For example, combining this rule and the previous section:
17207
17208 @example
17209 @@node @@b@{A@} @@TeX@{@} @@u@{B@} @@point@{@}@@enddots@{@}
17210 @result{} A-TeX-B_0306-_2605_002e_002e_002e
17211 @end example
17212
17213 Notice: 1)@tie{}@code{@@enddots} expands to three periods which in
17214 turn expands to three @samp{_002e}'s; 2)@tie{}@code{@@u@{B@}} is a `B'
17215 with a breve accent, which does not exist as a pre-accented Unicode
17216 character, therefore expands to @samp{B_0306} (B with combining
17217 breve).
17218
17219 When the Unicode code point is above 0xffff, the transformation is
17220 @samp{__@var{xxxxxx}}, that is, two leading underscores followed by
17221 six hex digits. Since Unicode has declared that their highest code
17222 point is 0x10ffff, this is sufficient. (We felt it was better to
17223 define this extra escape than to always use six hex digits, since the
17224 first two would nearly always be zeros.)
17225
17226 This method works fine if the node name consists mostly of ASCII
17227 characters and contains only few 8-bit ones. If the document is
17228 written in a language whose script is not based on the Latin alphabet
17229 (such as, e.g. Ukrainian), it will create file names consisting
17230 entirely of @samp{_@var{xxxx}} notations, which is inconvenient.
17231
17232 To handle such cases, @command{makeinfo} offers
17233 @option{--transliterate-file-names} command line option. This option
17234 enables @dfn{transliteration} of node names into ASCII characters for
17235 the purposes of file name creation and referencing. The
17236 transliteration is based on phonetic principle, which makes the
17237 produced file names easily readable.
17238
17239 For the definition of Unicode Normalization Form C, see Unicode report
17240 UAX#15, @uref{http://www.unicode.org/reports/tr15/}. Many related
17241 documents and implementations are available elsewhere on the web.
17242
17243
17244 @node HTML Xref Mismatch
17245 @subsection HTML Cross-reference Mismatch
17246 @cindex HTML cross-reference mismatch
17247 @cindex Mismatched HTML cross-reference source and target
17248
17249 As mentioned earlier (@pxref{HTML Xref Link Basics}), the generating
17250 software has to guess whether a given manual being cross-referenced is
17251 available in split or monolithic form---and, inevitably, it might
17252 guess wrong. However, it is possible when the referent manual itself
17253 is generated, it is possible to handle at least some mismatches.
17254
17255 In the case where we assume the referent is split, but it is actually
17256 available in mono, the only recourse would be to generate a
17257 @file{manual/} subdirectory full of HTML files which redirect back to
17258 the monolithic @file{manual.html}. Since this is essentially the same
17259 as a split manual in the first place, it's not very appealing.
17260
17261 On the other hand, in the case where we assume the referent is mono,
17262 but it is actually available in split, it is possible to use
17263 JavaScript to redirect from the putatively monolithic
17264 @file{manual.html} to the different @file{manual/node.html} files.
17265 Here's an example:
17266
17267 @example
17268 function redirect() @{
17269 switch (location.hash) @{
17270 case "#Node1":
17271 location.replace("manual/Node1.html#Node1"); break;
17272 case "#Node2" :
17273 location.replace("manual/Node2.html#Node2"); break;
17274 @dots{}
17275 default:;
17276 @}
17277 @}
17278 @end example
17279
17280 Then, in the @code{<body>} tag of @file{manual.html}:
17281
17282 @example
17283 <body onLoad="redirect();">
17284 @end example
17285
17286 Once again, this is something the software which generated the
17287 @emph{referent} manual has to do in advance, it's not something the
17288 software generating the actual cross-reference in the present manual
17289 can control.
17290
17291 Ultimately, we hope to allow for an external configuration file to
17292 control which manuals are available from where, and how.
17293
17294
17295 @ignore
17296 -- not yet --
17297
17298 external information
17299 --------------------
17300
17301 The information for the reference is searched in the file
17302 `htmlxref.cnf' present in the following directories:
17303 <srcdir>/.texinfo/, ~/.texinfo/, SYSCONFDIR/texinfo/,
17304 DATADIR/texinfo/
17305 The first match should be used.
17306
17307 The file is line-oriented, with the following format:
17308 <manualname> <whitespace> <keyword> <whitespace> <urlprefix>
17309 with <keyword> being "mono" or "split". Thus
17310 texinfo split http://www.gnu.org/software/texinfo/manual/texinfo/html_node/
17311 texinfo mono http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
17312
17313 If the keyword is 'split', that is the target is split, the urlprefix gives
17314 the directory and host name.
17315 If the keyword is 'mono', that is the target is mono, the urlprefix gives
17316 directory, host and file name.
17317
17318 '#' followed by a space begins comments. '#' followed by another character
17319 cannot begin comments as there are # in urls.
17320
17321 @end ignore
17322
17323
17324 @node Command List
17325 @appendix @@-Command List
17326 @cindex Alphabetical @@-command list
17327 @cindex List of @@-commands
17328 @cindex @@-command list
17329 @cindex Reference to @@-commands
17330
17331 Here is an alphabetical list of the @@-commands in Texinfo. Square
17332 brackets, @t{[}@w{ }@t{]}, indicate optional arguments; an ellipsis,
17333 @samp{@dots{}}, indicates repeated text.
17334
17335 More specifics on the general syntax of different @@-commands are
17336 given in the section below.
17337
17338 @menu
17339 * Command Syntax:: General syntax for varieties of @@-commands.
17340 @end menu
17341
17342 @sp 1
17343 @table @code
17344 @item @@@var{whitespace}
17345 An @code{@@} followed by a space, tab, or newline produces a normal,
17346 stretchable, interword space. @xref{Multiple Spaces}.
17347
17348 @item @@!
17349 Produce an exclamation point that ends a sentence (usually after an
17350 end-of-sentence capital letter). @xref{Ending a Sentence}.
17351
17352 @item @@"
17353 @itemx @@'
17354 Generate an umlaut or acute accent, respectively, over the next
17355 character, as in @"o and @'o. @xref{Inserting Accents}.
17356
17357 @item @@*
17358 Force a line break. @xref{Line Breaks}.
17359
17360 @item @@,@{@var{c}@}
17361 Generate a cedilla accent under @var{c}, as in @,{c}. @xref{Inserting
17362 Accents}.
17363
17364 @item @@-
17365 Insert a discretionary hyphenation point. @xref{- and hyphenation}.
17366
17367 @item @@.
17368 Produce a period that ends a sentence (usually after an
17369 end-of-sentence capital letter). @xref{Ending a Sentence}.
17370
17371 @item @@/
17372 Produces no output, but allows a line break. @xref{Line Breaks}.
17373
17374 @item @@:
17375 Tell @TeX{} to refrain from inserting extra whitespace after an
17376 immediately preceding period, question mark, exclamation mark, or
17377 colon, as @TeX{} normally would. @xref{Not Ending a Sentence}.
17378
17379 @item @@=
17380 Generate a macron (bar) accent over the next character, as in @=o.
17381 @xref{Inserting Accents}.
17382
17383 @item @@?
17384 Produce a question mark that ends a sentence (usually after an
17385 end-of-sentence capital letter). @xref{Ending a Sentence}.
17386
17387 @item @@@@
17388 Stands for an at sign, @samp{@@}.
17389 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
17390
17391 @item @@\
17392 Stands for a backslash (@samp{\}) inside @code{@@math}.
17393 @xref{math,,@code{math}}.
17394
17395 @item @@^
17396 @itemx @@`
17397 Generate a circumflex (hat) or grave accent, respectively, over the next
17398 character, as in @^o and @`e.
17399 @xref{Inserting Accents}.
17400
17401 @item @@@{
17402 Stands for a left brace, @samp{@{}.
17403 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
17404
17405 @item @@@}
17406 Stands for a right-hand brace, @samp{@}}.@*
17407 @xref{Atsign Braces Comma, , Inserting @@ and @{@} and @comma{}}.
17408
17409 @item @@~
17410 Generate a tilde accent over the next character, as in @~N.
17411 @xref{Inserting Accents}.
17412
17413 @item @@AA@{@}
17414 @itemx @@aa@{@}
17415 Generate the uppercase and lowercase Scandinavian A-ring letters,
17416 respectively: @AA{}, @aa{}. @xref{Inserting Accents}.
17417
17418 @item @@abbr@{@var{abbreviation}@}
17419 Indicate a general abbreviation, such as `Comput.'. @xref{abbr,,
17420 @code{abbr}}.
17421
17422 @item @@acronym@{@var{acronym}@}
17423 Indicate an acronym in all capital letters, such as `NASA'.
17424 @xref{acronym,, @code{acronym}}.
17425
17426 @item @@AE@{@}
17427 @itemx @@ae@{@}
17428 Generate the uppercase and lowercase AE ligatures, respectively:
17429 @AE{}, @ae{}. @xref{Inserting Accents}.
17430
17431 @itemx @@afivepaper
17432 Change page dimensions for the A5 paper size. @xref{A4 Paper}.
17433
17434 @item @@afourlatex
17435 @itemx @@afourpaper
17436 @itemx @@afourwide
17437 Change page dimensions for the A4 paper size. @xref{A4 Paper}.
17438
17439 @item @@alias @var{new}=@var{existing}
17440 Make the command @samp{@@@var{new}} a synonym for the existing command
17441 @samp{@@@var{existing}}. @xref{alias}.
17442
17443 @item @@anchor@{@var{name}@}
17444 Define @var{name} as the current location for use as a cross-reference
17445 target. @xref{anchor,, @code{@@anchor}}.
17446
17447 @item @@appendix @var{title}
17448 Begin an appendix. The title appears in the table of contents. In
17449 Info, the title is underlined with asterisks. @xref{unnumbered &
17450 appendix, , The @code{@@unnumbered} and @code{@@appendix} Commands}.
17451
17452 @item @@appendixsec @var{title}
17453 @itemx @@appendixsection @var{title}
17454 Begin an appendix section within an appendix. The section title
17455 appears in the table of contents. In Info, the title is underlined
17456 with equal signs. @code{@@appendixsection} is a longer spelling of
17457 the @code{@@appendixsec} command. @xref{unnumberedsec appendixsec
17458 heading, , Section Commands}.
17459
17460 @item @@appendixsubsec @var{title}
17461 Begin an appendix subsection. The title appears in the table of
17462 contents. In Info, the title is underlined with hyphens.
17463 @xref{unnumberedsubsec appendixsubsec subheading, , Subsection
17464 Commands}.
17465
17466 @item @@appendixsubsubsec @var{title}
17467 Begin an appendix subsubsection. The title appears in the table of
17468 contents. In Info, the title is underlined with periods.
17469 @xref{subsubsection,, The `subsub' Commands}.
17470
17471 @item @@arrow@{@}
17472 Generate a right arrow glyph: @samp{@arrow{}}. Used by default
17473 for @code{@@click}. @xref{Click Sequences}.
17474
17475 @item @@asis
17476 Used following @code{@@table}, @code{@@ftable}, and @code{@@vtable} to
17477 print the table's first column without highlighting (``as is'').
17478 @xref{Two-column Tables}.
17479
17480 @item @@author @var{author}
17481 Typeset @var{author} flushleft and underline it. @xref{title
17482 subtitle author, , The @code{@@title} and @code{@@author}
17483 Commands}.@refill
17484
17485 @item @@b@{@var{text}@}
17486 Set @var{text} in a @b{bold} font. No effect in Info. @xref{Fonts}.
17487
17488 @ignore
17489 @item @@br
17490 Force a paragraph break. If used within a line, follow @code{@@br}
17491 with braces. @xref{br, , @code{@@br}}.@refill
17492 @end ignore
17493
17494 @item @@bullet@{@}
17495 Generate a large round dot, @bullet{} (@samp{*} in Info). Often used
17496 with @code{@@table}. @xref{bullet, , @code{@@bullet}}.
17497
17498 @item @@bye
17499 Stop formatting a file. The formatters do not see anything in the
17500 input file following @code{@@bye}. @xref{Ending a File}.
17501
17502 @item @@c @var{comment}
17503 Begin a comment in Texinfo. The rest of the line does not appear in
17504 any output. A synonym for
17505 @code{@@comment}. @xref{Comments}.
17506
17507 @item @@caption
17508 Define the full caption for a @code{@@float}. @xref{caption shortcaption}.
17509
17510 @item @@cartouche
17511 Highlight an example or quotation by drawing a box with rounded
17512 corners around it. Pair with @code{@@end cartouche}. No effect in
17513 Info. @xref{cartouche, , Drawing Cartouches Around Examples}.)@refill
17514
17515 @item @@center @var{line-of-text}
17516 Center the line of text following the command.
17517 @xref{titlefont center sp, , @code{@@center}}.@refill
17518
17519 @item @@centerchap @var{line-of-text}
17520 Like @code{@@chapter}, but centers the chapter title. @xref{chapter,,
17521 @code{@@chapter}}.
17522
17523 @item @@chapheading @var{title}
17524 Print an unnumbered chapter-like heading, but omit from the table of
17525 contents. In Info, the title is underlined with asterisks.
17526 @xref{majorheading & chapheading, , @code{@@majorheading} and
17527 @code{@@chapheading}}.
17528
17529 @item @@chapter @var{title}
17530 Begin a numbered chapter. The chapter title appears in the table of
17531 contents. In Info, the title is underlined with asterisks.
17532 @xref{chapter, , @code{@@chapter}}.
17533
17534 @item @@cindex @var{entry}
17535 Add @var{entry} to the index of concepts. @xref{Index Entries, ,
17536 Defining the Entries of an Index}.@refill
17537
17538 @item @@cite@{@var{reference}@}
17539 Highlight the name of a book or other reference that has no companion
17540 Info file. @xref{cite, , @code{@@cite}}.
17541
17542 @item @@click@{@}
17543 Represent a single ``click'' in a GUI. Used within
17544 @code{@@clicksequence}. @xref{Click Sequences}.
17545
17546 @item @@clicksequence@{@var{action} @@click@{@} @var{action}@}
17547 Represent a sequence of clicks in a GUI. @xref{Click Sequences}.
17548
17549 @item @@clickstyle @@@var{cmd}
17550 Execute @@@var{cmd} for each @code{@@click}; the default is
17551 @code{@@arrow}. The usual following empty braces on @@@var{cmd} are
17552 omitted. @xref{Click Sequences}.
17553
17554 @item @@clear @var{flag}
17555 Unset @var{flag}, preventing the Texinfo formatting commands from
17556 formatting text between subsequent pairs of @code{@@ifset @var{flag}}
17557 and @code{@@end ifset} commands, and preventing
17558 @code{@@value@{@var{flag}@}} from expanding to the value to which
17559 @var{flag} is set.
17560 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
17561
17562 @item @@code@{@var{sample-code}@}
17563 Indicate an expression, a syntactically complete token of a program,
17564 or a program name. Unquoted in Info output. @xref{code, ,
17565 @code{@@code}}.
17566
17567 @item @@comma@{@}
17568 Insert a comma `,' character; only needed when a literal comma would
17569 be taken as an argument separator. @xref{Inserting a Comma}.
17570
17571 @item @@command@{@var{command-name}@}
17572 Indicate a command name, such as @command{ls}.
17573 @xref{command,, @code{@@command}}.
17574
17575 @item @@comment @var{comment}
17576 Begin a comment in Texinfo. The rest of the line does not appear in
17577 any output. A synonym for @code{@@c}.
17578 @xref{Comments}.
17579
17580 @item @@contents
17581 Print a complete table of contents. Has no effect in Info, which uses
17582 menus instead. @xref{Contents, , Generating a Table of
17583 Contents}.@refill
17584
17585 @item @@copyright@{@}
17586 Generate the copyright symbol @copyright{}. @xref{copyright symbol,,
17587 @code{@@copyright@{@}}}.
17588
17589 @ignore
17590 @item @@ctrl@{@var{ctrl-char}@}
17591 Describe an ASCII control character. Insert actual control character
17592 into Info file. @xref{ctrl, , @code{@@ctrl}}.
17593 @end ignore
17594
17595 @item @@defcodeindex @var{index-name}
17596 Define a new index and its indexing command. Print entries in an
17597 @code{@@code} font. @xref{New Indices, , Defining New Indices}.
17598
17599 @item @@defcv @var{category} @var{class} @var{name}
17600 @itemx @@defcvx @var{category} @var{class} @var{name}
17601 Format a description for a variable associated with a class in
17602 object-oriented programming. Takes three arguments: the category of
17603 thing being defined, the class to which it belongs, and its name.
17604 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17605
17606 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
17607 @itemx @@deffnx @var{category} @var{name} @var{arguments}@dots{}
17608 Format a description for a function, interactive command, or similar
17609 entity that may take arguments. @code{@@deffn} takes as arguments the
17610 category of entity being described, the name of this particular
17611 entity, and its arguments, if any. @xref{Definition Commands}.@refill
17612
17613 @item @@defindex @var{index-name}
17614 Define a new index and its indexing command. Print entries in a roman
17615 font. @xref{New Indices, , Defining New Indices}.@refill
17616
17617 @item @@definfoenclose @var{newcmd}, @var{before}, @var{after}
17618 Must be used within @code{@@ifinfo}; create a new command
17619 @code{@@@var{newcmd}} for Info that marks text by enclosing it in
17620 strings that precede and follow the text. @xref{definfoenclose}.
17621
17622 @item @@defivar @var{class} @var{instance-variable-name}
17623 @itemx @@defivarx @var{class} @var{instance-variable-name}
17624 Format a description for an instance variable in object-oriented
17625 programming. The command is equivalent to @samp{@@defcv @{Instance
17626 Variable@} @dots{}}. @xref{Definition Commands}, and @ref{deffnx,,
17627 Def Cmds in Detail}.
17628
17629 @item @@defmac @var{macroname} @var{arguments}@dots{}
17630 @itemx @@defmacx @var{macroname} @var{arguments}@dots{}
17631 Format a description for a macro; equivalent to @samp{@@deffn Macro
17632 @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
17633 Detail}.
17634
17635 @item @@defmethod @var{class} @var{method-name} @var{arguments}@dots{}
17636 @itemx @@defmethodx @var{class} @var{method-name} @var{arguments}@dots{}
17637 Format a description for a method in object-oriented programming;
17638 equivalent to @samp{@@defop Method @dots{}}. @xref{Definition
17639 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17640
17641 @item @@defop @var{category} @var{class} @var{name} @var{arguments}@dots{}
17642 @itemx @@defopx @var{category} @var{class} @var{name} @var{arguments}@dots{}
17643 Format a description for an operation in object-oriented programming.
17644 @code{@@defop} takes as arguments the name of the category of
17645 operation, the name of the operation's class, the name of the
17646 operation, and its arguments, if any. @xref{Definition Commands}, and
17647 @ref{Abstract Objects}.
17648
17649 @item @@defopt @var{option-name}
17650 @itemx @@defoptx @var{option-name}
17651 Format a description for a user option; equivalent to @samp{@@defvr
17652 @{User Option@} @dots{}}. @xref{Definition Commands}, and
17653 @ref{deffnx,, Def Cmds in Detail}.
17654
17655 @item @@defspec @var{special-form-name} @var{arguments}@dots{}
17656 @itemx @@defspecx @var{special-form-name} @var{arguments}@dots{}
17657 Format a description for a special form; equivalent to @samp{@@deffn
17658 @{Special Form@} @dots{}}. @xref{Definition Commands}, and
17659 @ref{deffnx,, Def Cmds in Detail}.
17660
17661 @item @@deftp @var{category} @var{name-of-type} @var{attributes}@dots{}
17662 @itemx @@deftpx @var{category} @var{name-of-type} @var{attributes}@dots{}
17663 Format a description for a data type; its arguments are the category,
17664 the name of the type (e.g., @samp{int}) , and then the names of
17665 attributes of objects of that type. @xref{Definition Commands}, and
17666 @ref{Data Types}.
17667
17668 @item @@deftypecv @var{category} @var{class} @var{data-type} @var{name}
17669 @itemx @@deftypecvx @var{category} @var{class} @var{data-type} @var{name}
17670 Format a description for a typed class variable in object-oriented programming.
17671 @xref{Definition Commands}, and @ref{Abstract Objects}.
17672
17673 @item @@deftypefn @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
17674 @itemx @@deftypefnx @var{category} @var{data-type} @var{name} @var{arguments}@dots{}
17675 Format a description for a function or similar entity that may take
17676 arguments and that is typed. @code{@@deftypefn} takes as arguments the
17677 category of entity being described, the type, the name of the
17678 entity, and its arguments, if any. @xref{Definition Commands}, and
17679 @ref{deffnx,, Def Cmds in Detail}.
17680
17681 @item @@deftypefun @var{data-type} @var{function-name} @var{arguments}@dots{}
17682 @itemx @@deftypefunx @var{data-type} @var{function-name} @var{arguments}@dots{}
17683 Format a description for a function in a typed language.
17684 The command is equivalent to @samp{@@deftypefn Function @dots{}}.
17685 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17686
17687 @item @@deftypeivar @var{class} @var{data-type} @var{variable-name}
17688 @itemx @@deftypeivarx @var{class} @var{data-type} @var{variable-name}
17689 Format a description for a typed instance variable in object-oriented
17690 programming. @xref{Definition Commands}, and @ref{Abstract Objects}.
17691
17692 @item @@deftypemethod @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
17693 @itemx @@deftypemethodx @var{class} @var{data-type} @var{method-name} @var{arguments}@dots{}
17694 Format a description for a typed method in object-oriented programming.
17695 @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17696
17697 @item @@deftypeop @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
17698 @itemx @@deftypeopx @var{category} @var{class} @var{data-type} @var{name} @var{arguments}@dots{}
17699 Format a description for a typed operation in object-oriented programming.
17700 @xref{Definition Commands}, and @ref{Abstract Objects}.
17701
17702 @item @@deftypevar @var{data-type} @var{variable-name}
17703 @itemx @@deftypevarx @var{data-type} @var{variable-name}
17704 Format a description for a variable in a typed language. The command is
17705 equivalent to @samp{@@deftypevr Variable @dots{}}. @xref{Definition
17706 Commands}, and @ref{deffnx,, Def Cmds in Detail}.
17707
17708 @item @@deftypevr @var{category} @var{data-type} @var{name}
17709 @itemx @@deftypevrx @var{category} @var{data-type} @var{name}
17710 Format a description for something like a variable in a typed
17711 language---an entity that records a value. Takes as arguments the
17712 category of entity being described, the type, and the name of the
17713 entity. @xref{Definition Commands}, and @ref{deffnx,, Def Cmds in
17714 Detail}.
17715
17716 @item @@defun @var{function-name} @var{arguments}@dots{}
17717 @itemx @@defunx @var{function-name} @var{arguments}@dots{}
17718 Format a description for a function; equivalent to
17719 @samp{@@deffn Function @dots{}}. @xref{Definition Commands}, and
17720 @ref{deffnx,, Def Cmds in Detail}.
17721
17722 @item @@defvar @var{variable-name}
17723 @itemx @@defvarx @var{variable-name}
17724 Format a description for a variable; equivalent to @samp{@@defvr
17725 Variable @dots{}}. @xref{Definition Commands}, and @ref{deffnx,, Def
17726 Cmds in Detail}.
17727
17728 @item @@defvr @var{category} @var{name}
17729 @itemx @@defvrx @var{category} @var{name}
17730 Format a description for any kind of variable. @code{@@defvr} takes
17731 as arguments the category of the entity and the name of the entity.
17732 @xref{Definition Commands},
17733 and @ref{deffnx,, Def Cmds in Detail}.
17734
17735 @item @@detailmenu
17736 Mark the (optional) detailed node listing in a master menu.
17737 @xref{Master Menu Parts}.
17738
17739 @item @@dfn@{@var{term}@}
17740 Indicate the introductory or defining use of a term. @xref{dfn, ,
17741 @code{@@dfn}}.
17742
17743 @item @@dircategory @var{dirpart}
17744 Specify a part of the Info directory menu where this file's entry should
17745 go. @xref{Installing Dir Entries}.
17746
17747 @item @@direntry
17748 Begin the Info directory menu entry for this file. Pair with
17749 @code{@@end direntry}. @xref{Installing Dir Entries}.
17750
17751 @item @@display
17752 Begin a kind of example. Like @code{@@example} (indent text, do not
17753 fill), but do not select a new font. Pair with @code{@@end display}.
17754 @xref{display, , @code{@@display}}.
17755
17756 @item @@dmn@{@var{dimension}@}
17757 Format a unit of measure, as in 12@dmn{pt}. Causes @TeX{} to insert a
17758 thin space before @var{dimension}. No effect in Info.
17759 @xref{dmn, , @code{@@dmn}}.
17760
17761 @item @@docbook
17762 Enter Docbook completely. Pair with @code{@@end docbook}. @xref{Raw
17763 Formatter Commands}.
17764
17765 @item @@documentdescription
17766 Set the document description text, included in the HTML output. Pair
17767 with @code{@@end documentdescription}. @xref{documentdescription,,
17768 @code{@@documentdescription}}.
17769
17770 @item @@documentencoding @var{enc}
17771 Declare the input encoding to be @var{enc}.
17772 @xref{documentencoding,, @code{@@documentencoding}}.
17773
17774 @item @@documentlanguage @var{CC}
17775 Declare the document language as the two-character ISO-639 abbreviation
17776 @var{CC}. @xref{documentlanguage,, @code{@@documentlanguage}}.
17777
17778 @item @@dotaccent@{@var{c}@}
17779 Generate a dot accent over the character @var{c}, as in @dotaccent{o}.
17780 @xref{Inserting Accents}.
17781
17782 @item @@dots@{@}
17783 Generate an ellipsis, @samp{@dots{}}.
17784 @xref{dots, , @code{@@dots}}.@refill
17785
17786 @item @@email@{@var{address}[, @var{displayed-text}]@}
17787 Indicate an electronic mail address.
17788 @xref{email, , @code{@@email}}.
17789
17790 @item @@emph@{@var{text}@}
17791 Emphasize @var{text}, by using @emph{italics} where possible, and
17792 enclosing in asterisks in Info. @xref{Emphasis, , Emphasizing Text}.
17793
17794 @item @@end @var{environment}
17795 Ends @var{environment}, as in @samp{@@end example}. @xref{Formatting
17796 Commands,,@@-commands}.
17797
17798 @item @@env@{@var{environment-variable}@}
17799 Indicate an environment variable name, such as @env{PATH}.
17800 @xref{env,, @code{@@env}}.
17801
17802 @item @@enddots@{@}
17803 Generate an end-of-sentence ellipsis, like this: @enddots{}
17804 @xref{dots,,@code{@@dots@{@}}}.
17805
17806 @item @@enumerate [@var{number-or-letter}]
17807 Begin a numbered list, using @code{@@item} for each entry.
17808 Optionally, start list with @var{number-or-letter}. Pair with
17809 @code{@@end enumerate}. @xref{enumerate, ,
17810 @code{@@enumerate}}.@refill
17811
17812 @item @@equiv@{@}
17813 Indicate to the reader the exact equivalence of two forms with a
17814 glyph: @samp{@equiv{}}. @xref{Equivalence}.@refill
17815
17816 @item @@euro@{@}
17817 Generate the Euro currency sign.
17818 @xref{euro,,@code{@@euro@{@}}}.
17819
17820 @item @@error@{@}
17821 Indicate to the reader with a glyph that the following text is
17822 an error message: @samp{@error{}}. @xref{Error Glyph}.@refill
17823
17824 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
17825 @itemx @@evenheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
17826 Specify page footings resp.@: headings for even-numbered (left-hand)
17827 pages. @xref{Custom Headings, ,
17828 How to Make Your Own Headings}.@refill
17829
17830 @item @@everyfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
17831 @itemx @@everyheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
17832 Specify page footings resp.@: headings for every page. Not relevant to
17833 Info. @xref{Custom Headings, , How to Make Your Own Headings}.
17834
17835 @item @@example
17836 Begin an example. Indent text, do not fill, and select fixed-width
17837 font. Pair with @code{@@end example}. @xref{example,, @code{@@example}}.
17838
17839 @item @@exampleindent @var{indent}
17840 Indent example-like environments by @var{indent} number of spaces
17841 (perhaps 0). @xref{exampleindent,, Paragraph Indenting}.
17842
17843 @item @@exclamdown@{@}
17844 Generate an upside-down exclamation point. @xref{Inserting Accents}.
17845
17846 @item @@exdent @var{line-of-text}
17847 Remove any indentation a line might have. @xref{exdent, ,
17848 Undoing the Indentation of a Line}.@refill
17849
17850 @item @@expansion@{@}
17851 Indicate the result of a macro expansion to the reader with a special
17852 glyph: @samp{@expansion{}}.
17853 @xref{expansion, , @expansion{} Indicating an Expansion}.@refill
17854
17855 @item @@file@{@var{filename}@}
17856 Highlight the name of a file, buffer, node, directory, etc. @xref{file, ,
17857 @code{@@file}}.
17858
17859 @item @@finalout
17860 Prevent @TeX{} from printing large black warning rectangles beside
17861 over-wide lines. @xref{Overfull hboxes}.@refill
17862
17863 @item @@findex @var{entry}
17864 Add @var{entry} to the index of functions. @xref{Index Entries, ,
17865 Defining the Entries of an Index}.@refill
17866
17867 @item @@float
17868 Environment to define floating material. Pair with @code{@@end float}.
17869 @xref{Floats}.
17870
17871 @item @@flushleft
17872 @itemx @@flushright
17873 Do not fill text; left (right) justify every line while leaving the
17874 right (left) end ragged. Leave font as is. Pair with @code{@@end
17875 flushleft} (@code{@@end flushright}). @code{@@flushright} analogous.
17876 @xref{flushleft & flushright, , @code{@@flushleft} and
17877 @code{@@flushright}}.
17878
17879 @item @@footnote@{@var{text-of-footnote}@}
17880 Enter a footnote. Footnote text is printed at the bottom of the page
17881 by @TeX{}; Info may format in either `End' node or `Separate' node style.
17882 @xref{Footnotes}.
17883
17884 @item @@footnotestyle @var{style}
17885 Specify an Info file's footnote style, either @samp{end} for the end
17886 node style or @samp{separate} for the separate node style.
17887 @xref{Footnotes}.
17888
17889 @item @@format
17890 Begin a kind of example. Like @code{@@display}, but do not indent.
17891 Pair with @code{@@end format}. @xref{example,, @code{@@example}}.
17892
17893 @item @@ftable @var{formatting-command}
17894 Begin a two-column table, using @code{@@item} for each entry.
17895 Automatically enter each of the items in the first column into the
17896 index of functions. Pair with @code{@@end ftable}. The same as
17897 @code{@@table}, except for indexing. @xref{ftable vtable, ,
17898 @code{@@ftable} and @code{@@vtable}}.@refill
17899
17900 @item @@geq@{@}
17901 Generate a greater-than-or-equal sign, `@geq{}'. @xref{geq leq}.
17902
17903 @item @@group
17904 Disallow page breaks within following text. Pair with @code{@@end
17905 group}. Ignored in Info. @xref{group, , @code{@@group}}.
17906
17907 @item @@H@{@var{c}@}
17908 Generate the long Hungarian umlaut accent over @var{c}, as in @H{o}.
17909
17910 @item @@heading @var{title}
17911 Print an unnumbered section-like heading, but omit from the table of
17912 contents. In Info, the title is underlined with equal signs.
17913 @xref{unnumberedsec appendixsec heading, , Section Commands}.
17914
17915 @item @@headings @var{on-off-single-double}
17916 Turn page headings on or off, and/or specify single-sided or double-sided
17917 page headings for printing. @xref{headings on off, , The
17918 @code{@@headings} Command}.
17919
17920 @item @@headitem
17921 Begin a heading row in a multitable. @xref{Multitable Rows}.
17922
17923 @item @@html
17924 Enter HTML completely. Pair with @code{@@end html}. @xref{Raw
17925 Formatter Commands}.
17926
17927 @item @@hyphenation@{@var{hy-phen-a-ted words}@}
17928 Explicitly define hyphenation points. @xref{- and hyphenation,,
17929 @code{@@-} and @code{@@hyphenation}}.
17930
17931 @item @@i@{@var{text}@}
17932 Set @var{text} in an @i{italic} font. No effect in Info. @xref{Fonts}.
17933
17934 @item @@ifclear @var{txivar}
17935 If the Texinfo variable @var{txivar} is not set, format the following
17936 text. Pair with @code{@@end ifclear}. @xref{set clear value, ,
17937 @code{@@set} @code{@@clear} @code{@@value}}.
17938
17939 @item @@ifdocbook
17940 @itemx @@ifhtml
17941 @itemx @@ifinfo
17942 Begin text that will appear only in the given output format.
17943 @code{@@ifinfo} output appears in both Info and (for historical
17944 compatibility) plain text output. Pair with @code{@@end ifdocbook}
17945 resp.@: @code{@@end ifhtml} resp.@: @code{@@end ifinfo}.
17946 @xref{Conditionals}.
17947
17948 @item @@ifnotdocbook
17949 @itemx @@ifnothtml
17950 @itemx @@ifnotplaintext
17951 @itemx @@ifnottex
17952 @itemx @@ifnotxml
17953 Begin text to be ignored in one output format but not the others.
17954 @code{@@ifnothtml} text is omitted from HTML output, etc. Pair with
17955 the corresponding @code{@@end ifnot@var{format}}.
17956 @xref{Conditionals}.
17957
17958 @itemx @@ifnotinfo
17959 Begin text to appear in output other than Info and (for historical
17960 compatibility) plain text. Pair with @code{@@end ifnotinfo}.
17961 @xref{Conditionals}.
17962
17963 @item @@ifplaintext
17964 Begin text that will appear only in the plain text output.
17965 Pair with @code{@@end ifplaintext}. @xref{Conditionals}.
17966
17967 @item @@ifset @var{txivar}
17968 If the Texinfo variable @var{txivar} is set, format the following
17969 text. Pair with @code{@@end ifset}. @xref{set clear value, ,
17970 @code{@@set} @code{@@clear} @code{@@value}}.
17971
17972 @item @@iftex
17973 Begin text to appear only in the @TeX{} output. Pair with @code{@@end
17974 iftex}. @xref{Conditionals, , Conditionally Visible Text}.@refill
17975
17976 @item @@ifxml
17977 Begin text that will appear only in the XML output. Pair with
17978 @code{@@end ifxml}. @xref{Conditionals}.
17979
17980 @item @@ignore
17981 Begin text that will not appear in any output. Pair with @code{@@end
17982 ignore}. @xref{Comments, , Comments and Ignored Text}.
17983
17984 @item @@image@{@var{filename}, [@var{width}], [@var{height}], [@var{alt}], [@var{ext}]@}
17985 Include graphics image in external @var{filename} scaled to the given
17986 @var{width} and/or @var{height}, using @var{alt} text and looking for
17987 @samp{@var{filename}.@var{ext}} in HTML. @xref{Images}.
17988
17989 @item @@include @var{filename}
17990 Read the contents of Texinfo source file @var{filename}. @xref{Include Files}.
17991
17992 @item @@indicateurl@{@var{indicateurl}@}
17993 Indicate text that is a uniform resource locator for the World Wide
17994 Web. @xref{indicateurl, , @code{@@indicateurl}}.
17995
17996 @item @@inforef@{@var{node-name}, [@var{entry-name}], @var{info-file-name}@}
17997 Make a cross reference to an Info file for which there is no printed
17998 manual. @xref{inforef, , Cross references using
17999 @code{@@inforef}}.@refill
18000
18001 @item \input @var{macro-definitions-file}
18002 Use the specified macro definitions file. This command is used only
18003 in the first line of a Texinfo file to cause @TeX{} to make use of the
18004 @file{texinfo} macro definitions file. The backslash in @code{\input}
18005 is used instead of an @code{@@} because @TeX{} does not
18006 recognize @code{@@} until after it has read the definitions file.
18007 @xref{Texinfo File Header}.
18008
18009 @item @@item
18010 Indicate the beginning of a marked paragraph for @code{@@itemize} and
18011 @code{@@enumerate}; indicate the beginning of the text of a first column
18012 entry for @code{@@table}, @code{@@ftable}, and @code{@@vtable}.
18013 @xref{Lists and Tables}.
18014
18015 @item @@itemize @var{mark-generating-character-or-command}
18016 Begin an unordered list: indented paragraphs with a mark, such as
18017 @code{@@bullet}, inside the left margin at the beginning of each
18018 item. Pair with @code{@@end itemize}. @xref{itemize, ,
18019 @code{@@itemize}}.
18020
18021 @item @@itemx
18022 Like @code{@@item} but do not generate extra vertical space above the
18023 item text. Thus, when several items have the same description, use
18024 @code{@@item} for the first and @code{@@itemx} for the others.
18025 @xref{itemx, , @code{@@itemx}}.
18026
18027 @item @@kbd@{@var{keyboard-characters}@}
18028 Indicate characters of input to be typed by users. @xref{kbd, ,
18029 @code{@@kbd}}.
18030
18031 @item @@kbdinputstyle @var{style}
18032 Specify when @code{@@kbd} should use a font distinct from
18033 @code{@@code}. @xref{kbd, , @code{@@kbd}}.
18034
18035 @item @@key@{@var{key-name}@}
18036 Indicate the name of a key on a keyboard. @xref{key, , @code{@@key}}.
18037
18038 @item @@kindex @var{entry}
18039 Add @var{entry} to the index of keys.
18040 @xref{Index Entries, , Defining the Entries of an Index}.@refill
18041
18042 @item @@L@{@}
18043 @itemx @@l@{@}
18044 Generate the uppercase and lowercase Polish suppressed-L letters,
18045 respectively: @L{}, @l{}.
18046
18047 @item @@LaTeX@{@}
18048 Generate the @LaTeX{} logo. @xref{tex, , @TeX{} and @LaTeX{}}.
18049
18050 @item @@leq@{@}
18051 Generate a less-than-or-equal sign, `@leq{}'. @xref{geq leq}.
18052
18053 @item @@lisp
18054 Begin an example of Lisp code. Indent text, do not fill, and select
18055 fixed-width font. Pair with @code{@@end lisp}. @xref{lisp, , @code{@@lisp}}.
18056
18057 @item @@listoffloats
18058 Produce a table-of-contents-like listing of @code{@@float}s.
18059 @xref{listoffloats}.
18060
18061 @item @@lowersections
18062 Change subsequent chapters to sections, sections to subsections, and so
18063 on. @xref{Raise/lower sections, , @code{@@raisesections} and
18064 @code{@@lowersections}}.@refill
18065
18066 @item @@macro @var{macroname} @{@var{params}@}
18067 Define a new Texinfo command @code{@@@var{macroname}@{@var{params}@}}.
18068 Pair with @code{@@end macro}. @xref{Defining Macros}.
18069
18070 @item @@majorheading @var{title}
18071 Print an unnumbered chapter-like heading, but omit from
18072 the table of contents. This generates more vertical whitespace before
18073 the heading than the @code{@@chapheading} command. @xref{majorheading
18074 & chapheading, , @code{@@majorheading} and @code{@@chapheading}}.
18075
18076 @item @@math@{@var{mathematical-expression}@}
18077 Format a mathematical expression.
18078 @xref{math, , @code{@@math} - Inserting Mathematical Expressions}.
18079
18080 @item @@menu
18081 Mark the beginning of a menu of nodes. No effect in a printed manual.
18082 Pair with @code{@@end menu}. @xref{Menus}.
18083
18084 @item @@minus@{@}
18085 Generate a minus sign, `@minus{}'. @xref{minus, , @code{@@minus}}.
18086
18087 @item @@multitable @var{column-width-spec}
18088 Begin a multi-column table. Begin each row with @code{@@item} or
18089 @code{@@headitem}, and separate columns with @code{@@tab}. Pair with
18090 @code{@@end multitable}. @xref{Multitable Column Widths}.
18091
18092 @item @@need @var{n}
18093 Start a new page in a printed manual if fewer than @var{n} mils
18094 (thousandths of an inch) remain on the current page. @xref{need, ,
18095 @code{@@need}}.
18096
18097 @item @@node @var{name}, @var{next}, @var{previous}, @var{up}
18098 Begin a new node. @xref{node, , @code{@@node}}.
18099
18100 @item @@noindent
18101 Prevent text from being indented as if it were a new paragraph.
18102 @xref{noindent, , @code{@@noindent}}.
18103
18104 @item @@novalidate
18105 Suppress validation of node references and omit creation of auxiliary
18106 files with @TeX{}. Use before @code{@@setfilename}. @xref{Pointer
18107 Validation}.
18108
18109 @item @@O@{@}
18110 @itemx @@o@{@}
18111 Generate the uppercase and lowercase O-with-slash letters, respectively:
18112 @O{}, @o{}.
18113
18114 @item @@oddfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
18115 @itemx @@oddheading [@var{left}] @@| [@var{center}] @@| [@var{right}]
18116 Specify page footings resp.@: headings for odd-numbered (right-hand)
18117 pages. @xref{Custom Headings, ,
18118 How to Make Your Own Headings}.@refill
18119
18120 @item @@OE@{@}
18121 @itemx @@oe@{@}
18122 Generate the uppercase and lowercase OE ligatures, respectively:
18123 @OE{}, @oe{}. @xref{Inserting Accents}.
18124
18125 @item @@option@{@var{option-name}@}
18126 Indicate a command-line option, such as @option{-l} or @option{--help}.
18127 @xref{option,, @code{@@option}}.
18128
18129 @item @@page
18130 Start a new page in a printed manual. No effect in Info.
18131 @xref{page, , @code{@@page}}.@refill
18132
18133 @item @@pagesizes [@var{width}][, @var{height}]
18134 Change page dimensions. @xref{pagesizes}.
18135
18136 @item @@paragraphindent @var{indent}
18137 Indent paragraphs by @var{indent} number of spaces (perhaps 0); preserve
18138 source file indentation if @var{indent} is @code{asis}.
18139 @xref{paragraphindent,, Paragraph Indenting}.
18140
18141 @item @@pindex @var{entry}
18142 Add @var{entry} to the index of programs. @xref{Index Entries, , Defining
18143 the Entries of an Index}.@refill
18144
18145 @item @@point@{@}
18146 Indicate the position of point in a buffer to the reader with a
18147 glyph: @samp{@point{}}. @xref{Point Glyph, , Indicating
18148 Point in a Buffer}.@refill
18149
18150 @item @@pounds@{@}
18151 Generate the pounds sterling currency sign.
18152 @xref{pounds,,@code{@@pounds@{@}}}.
18153
18154 @item @@print@{@}
18155 Indicate printed output to the reader with a glyph:
18156 @samp{@print{}}. @xref{Print Glyph}.@refill
18157
18158 @item @@printindex @var{index-name}
18159 Generate the alphabetized index for @var{index-name} (using two columns in a printed
18160 manual). @xref{Printing Indices & Menus}.
18161
18162 @item @@pxref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
18163 Make a reference that starts with a lower case `see' in a printed
18164 manual. Use within parentheses only. Only the first argument is
18165 mandatory. @xref{pxref, , @code{@@pxref}}.
18166
18167 @item @@questiondown@{@}
18168 Generate an upside-down question mark. @xref{Inserting Accents}.
18169
18170 @item @@quotation
18171 Narrow the margins to indicate text that is quoted from another work.
18172 Takes optional argument of prefix text. Pair with @code{@@end
18173 quotation}. @xref{quotation, , @code{@@quotation}}.
18174
18175 @item @@r@{@var{text}@}
18176 Set @var{text} in the regular @r{roman} font. No effect in Info.
18177 @xref{Fonts}.
18178
18179 @item @@raisesections
18180 Change subsequent sections to chapters, subsections to sections, and so
18181 on. @xref{Raise/lower sections, , @code{@@raisesections} and
18182 @code{@@lowersections}}.@refill
18183
18184 @item @@ref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
18185 Make a plain reference that does not start with any special text.
18186 Follow command with a punctuation mark. Only the first argument is
18187 mandatory. @xref{ref, , @code{@@ref}}.
18188
18189 @item @@refill
18190 This command used to refill and indent the paragraph after all the
18191 other processing has been done. It is no longer needed, since all
18192 formatters now automatically refill as needed, but you may still see
18193 it in the source to some manuals, as it does no harm.
18194
18195 @item @@registeredsymbol@{@}
18196 Generate the legal symbol @registeredsymbol{}. @xref{registered
18197 symbol,, @code{@@registeredsymbol@{@}}}.
18198
18199 @item @@result@{@}
18200 Indicate the result of an expression to the reader with a special
18201 glyph: @samp{@result{}}. @xref{result, , @code{@@result}}.@refill
18202
18203 @item @@ringaccent@{@var{c}@}
18204 Generate a ring accent over the next character, as in @ringaccent{o}.
18205 @xref{Inserting Accents}.
18206
18207 @item @@samp@{@var{text}@}
18208 Indicate a literal example of a sequence of characters, in general.
18209 Quoted in Info output. @xref{samp, , @code{@@samp}}.
18210
18211 @item @@sansserif@{@var{text}@}
18212 Set @var{text} in a @sansserif{sans serif} font if possible. No
18213 effect in Info. @xref{Fonts}.
18214
18215 @item @@sc@{@var{text}@}
18216 Set @var{text} in a small caps font in printed output, and uppercase
18217 in Info. @xref{Smallcaps}.
18218
18219 @item @@section @var{title}
18220 Begin a section within a chapter. The section title appears in the
18221 table of contents. In Info, the title is underlined with equal signs.
18222 Within @code{@@chapter} and @code{@@appendix}, the section title is
18223 numbered; within @code{@@unnumbered}, the section is unnumbered.
18224 @xref{section, , @code{@@section}}.
18225
18226 @item @@set @var{txivar} [@var{string}]
18227 Define the Texinfo variable @var{txivar}, optionally to the value
18228 @var{string}. @xref{set clear value, , @code{@@set} @code{@@clear}
18229 @code{@@value}}.
18230
18231 @item @@setchapternewpage @var{on-off-odd}
18232 Specify whether chapters start on new pages, and if so, whether on
18233 odd-numbered (right-hand) new pages. @xref{setchapternewpage, ,
18234 @code{@@setchapternewpage}}.
18235
18236 @item @@setcontentsaftertitlepage
18237 Put the table of contents after the @samp{@@end titlepage} even if the
18238 @code{@@contents} command is at the end. @xref{Contents}.
18239
18240 @item @@setfilename @var{info-file-name}
18241 Provide a name to be used for the output files. This command is essential
18242 for @TeX{} formatting as well, even though it produces no output of
18243 its own. @xref{setfilename, , @code{@@setfilename}}.
18244
18245 @item @@setshortcontentsaftertitlepage
18246 Place the short table of contents after the @samp{@@end titlepage}
18247 command even if the @code{@@shortcontents} command is at the end.
18248 @xref{Contents}.
18249
18250 @item @@settitle @var{title}
18251 Specify the title for page headers in a printed manual, and the
18252 default document description for HTML @samp{<head>}. @xref{settitle,,
18253 @code{@@settitle}}.
18254
18255 @item @@shortcaption
18256 Define the short caption for a @code{@@float}. @xref{caption shortcaption}.
18257
18258 @item @@shortcontents
18259 Print a short table of contents, with chapter-level entries only. Not
18260 relevant to Info, which uses menus rather than tables of contents.
18261 @xref{Contents, , Generating a Table of Contents}.
18262
18263 @item @@shorttitlepage @var{title}
18264 Generate a minimal title page. @xref{titlepage,,@code{@@titlepage}}.
18265
18266 @item @@slanted@{@var{text}@}
18267 Set @var{text} in a @slanted{slanted} font if possible. No effect
18268 in Info. @xref{Fonts}.
18269
18270 @item @@smallbook
18271 Cause @TeX{} to produce a printed manual in a 7 by 9.25 inch format
18272 rather than the regular 8.5 by 11 inch format. @xref{smallbook, ,
18273 Printing Small Books}. Also, see @ref{small}.
18274
18275 @item @@smalldisplay
18276 Begin a kind of example. Like @code{@@smallexample} (narrow margins, no
18277 filling), but do not select the fixed-width font. Pair with @code{@@end
18278 smalldisplay}. @xref{small}.
18279
18280 @item @@smallexample
18281 Begin an example. Do not fill, select fixed-width font, narrow the
18282 margins. Where possible, print text in a smaller font than with
18283 @code{@@example}. Pair with @code{@@end smallexample}. @xref{small}.
18284
18285 @item @@smallformat
18286 Begin a kind of example. Like @code{@@smalldisplay}, but do not narrow
18287 the margins. Pair with @code{@@end smallformat}. @xref{small}.
18288
18289 @item @@smalllisp
18290 Begin an example of Lisp code. Same as @code{@@smallexample}. Pair
18291 with @code{@@end smalllisp}. @xref{small}.
18292
18293 @item @@sp @var{n}
18294 Skip @var{n} blank lines. @xref{sp, , @code{@@sp}}.@refill
18295
18296 @item @@ss@{@}
18297 Generate the German sharp-S es-zet letter, @ss{}. @xref{Inserting Accents}.
18298
18299 @item @@strong @{@var{text}@}
18300 Emphasize @var{text} more strongly than @code{@@emph}, by using
18301 @strong{boldface} where possible; enclosed in asterisks in Info.
18302 @xref{emph & strong, , Emphasizing Text}.
18303
18304 @item @@subheading @var{title}
18305 Print an unnumbered subsection-like heading, but omit from the table
18306 of contents of a printed manual. In Info, the title is underlined
18307 with hyphens. @xref{unnumberedsubsec appendixsubsec subheading, ,
18308 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
18309 @code{@@subheading}}.
18310
18311 @item @@subsection @var{title}
18312 Begin a subsection within a section. The subsection title appears in
18313 the table of contents. In Info, the title is underlined with hyphens.
18314 Same context-dependent numbering as @code{@@section}. @xref{subsection, ,
18315 @code{@@subsection}}.
18316
18317 @item @@subsubheading @var{title}
18318 Print an unnumbered subsubsection-like heading, but omit from the
18319 table of contents of a printed manual. In Info, the title is
18320 underlined with periods. @xref{subsubsection, , The `subsub'
18321 Commands}.
18322
18323 @item @@subsubsection @var{title}
18324 Begin a subsubsection within a subsection. The subsubsection title
18325 appears in the table of contents. In Info, the title is underlined
18326 with periods. Same context-dependent numbering as @code{@@section}.
18327 @xref{subsubsection, , The `subsub' Commands}.
18328
18329 @item @@subtitle @var{title}
18330 In a printed manual, set a subtitle in a normal sized font flush to
18331 the right-hand side of the page. Not relevant to Info, which does not
18332 have title pages. @xref{title subtitle author, , @code{@@title}
18333 @code{@@subtitle} and @code{@@author} Commands}.
18334
18335 @item @@summarycontents
18336 Print a short table of contents. Synonym for @code{@@shortcontents}.
18337 @xref{Contents, , Generating a Table of Contents}.
18338
18339 @item @@syncodeindex @var{from-index} @var{to-index}
18340 Merge the index named in the first argument into the index named in
18341 the second argument, formatting the entries from the first index with
18342 @code{@@code} . @xref{Combining Indices}.@refill
18343
18344 @item @@synindex @var{from-index} @var{to-index}
18345 Merge the index named in the first argument into the index named in
18346 the second argument. Do not change the font of @var{from-index}
18347 entries. @xref{Combining Indices}.
18348
18349 @item @@t@{@var{text}@}
18350 Set @var{text} in a @t{fixed-width}, typewriter-like font. No effect
18351 in Info. @xref{Fonts}.
18352
18353 @item @@tab
18354 Separate columns in a row of a multitable. @xref{Multitable Rows}.
18355
18356 @item @@table @var{formatting-command}
18357 Begin a two-column table (description list), using @code{@@item} for
18358 each entry. Write each first column entry on the same line as
18359 @code{@@item}. First column entries are printed in the font resulting
18360 from @var{formatting-command}. Pair with @code{@@end table}.
18361 @xref{Two-column Tables, , Making a Two-column Table}. Also see
18362 @ref{ftable vtable, , @code{@@ftable} and @code{@@vtable}}, and
18363 @ref{itemx, , @code{@@itemx}}.
18364
18365 @item @@TeX@{@}
18366 Generate the @TeX{} logo. @xref{tex, , @TeX{} and @LaTeX{}}.
18367
18368 @item @@tex
18369 Enter @TeX{} completely. Pair with @code{@@end tex}. @xref{Raw
18370 Formatter Commands}.
18371
18372 @item @@thischapter
18373 @itemx @@thischaptername
18374 @itemx @@thischapternum
18375 @itemx @@thisfile
18376 @itemx @@thispage
18377 @itemx @@thistitle
18378 Only allowed in a heading or footing. Stands for, respectively, the
18379 number and name of the current chapter (in the format `Chapter 1:
18380 Title'), the current chapter name only, the current chapter number
18381 only, the filename, the current page number, and the title of the
18382 document, respectively. @xref{Custom Headings, , How to Make Your Own
18383 Headings}.
18384
18385 @item @@tie@{@}
18386 Generate a normal interword space at which a line break is not allowed.
18387 @xref{tie,, @code{@@tie@{@}}}.
18388
18389 @item @@tieaccent@{@var{cc}@}
18390 Generate a tie-after accent over the next two characters @var{cc}, as in
18391 `@tieaccent{oo}'. @xref{Inserting Accents}.
18392
18393 @item @@tindex @var{entry}
18394 Add @var{entry} to the index of data types. @xref{Index Entries, ,
18395 Defining the Entries of an Index}.@refill
18396
18397 @item @@title @var{title}
18398 In a printed manual, set a title flush to the left-hand side of the
18399 page in a larger than normal font and underline it with a black rule.
18400 Not relevant to Info, which does not have title pages. @xref{title
18401 subtitle author, , The @code{@@title} @code{@@subtitle} and
18402 @code{@@author} Commands}.@refill
18403
18404 @item @@titlefont@{@var{text}@}
18405 In a printed manual, print @var{text} in a larger than normal font.
18406 @xref{titlefont center sp, , The @code{@@titlefont} @code{@@center}
18407 and @code{@@sp} Commands}.
18408
18409 @item @@titlepage
18410 Begin the title page. Write the command on a line of its own, paired
18411 with @code{@@end titlepage}. Nothing between @code{@@titlepage} and
18412 @code{@@end titlepage} appears in Info. @xref{titlepage, ,
18413 @code{@@titlepage}}.@refill
18414
18415 @item @@today@{@}
18416 Insert the current date, in `1 Jan 1900' style. @xref{Custom
18417 Headings, , How to Make Your Own Headings}.@refill
18418
18419 @item @@top @var{title}
18420 Mark the topmost @code{@@node} in the file, which must be defined on
18421 the line immediately preceding the @code{@@top} command. The title is
18422 formatted as a chapter-level heading. The entire top node, including
18423 the @code{@@node} and @code{@@top} lines, are normally enclosed with
18424 @code{@@ifnottex ... @@end ifnottex}. In @TeX{} and
18425 @code{texinfo-format-buffer}, the @code{@@top} command is merely a
18426 synonym for @code{@@unnumbered}. @xref{makeinfo Pointer Creation, ,
18427 Creating Pointers with @code{makeinfo}}.
18428
18429 @item @@u@{@var{c}@}
18430 @itemx @@ubaraccent@{@var{c}@}
18431 @itemx @@udotaccent@{@var{c}@}
18432 Generate a breve, underbar, or underdot accent, respectively, over or
18433 under the character @var{c}, as in @u{o}, @ubaraccent{o},
18434 @udotaccent{o}. @xref{Inserting Accents}.
18435
18436 @item @@unnumbered @var{title}
18437 Begin a chapter that appears without chapter numbers of any kind. The
18438 title appears in the table of contents. In Info, the title is
18439 underlined with asterisks. @xref{unnumbered & appendix, ,
18440 @code{@@unnumbered} and @code{@@appendix}}.
18441
18442 @item @@unnumberedsec @var{title}
18443 Begin a section that appears without section numbers of any kind. The
18444 title appears in the table of contents of a printed manual. In Info,
18445 the title is underlined with equal signs. @xref{unnumberedsec
18446 appendixsec heading, , Section Commands}.
18447
18448 @item @@unnumberedsubsec @var{title}
18449 Begin an unnumbered subsection. The title appears in the table of
18450 contents. In Info, the title is underlined with hyphens.
18451 @xref{unnumberedsubsec appendixsubsec subheading, ,
18452 @code{@@unnumberedsubsec} @code{@@appendixsubsec}
18453 @code{@@subheading}}.
18454
18455 @item @@unnumberedsubsubsec @var{title}
18456 Begin an unnumbered subsubsection. The title appears in the table of
18457 contents. In Info, the title is underlined with periods.
18458 @xref{subsubsection, , The `subsub' Commands}.
18459
18460 @item @@uref@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
18461 @itemx @@url@{@var{url}[, @var{displayed-text}][, @var{replacement}@}
18462 Define a cross reference to an external uniform resource locator,
18463 e.g., for the World Wide Web. @xref{uref, , @code{@@uref}}.
18464
18465 @item @@v@{@var{c}@}
18466 Generate check accent over the character @var{c}, as in @v{o}.
18467 @xref{Inserting Accents}.
18468
18469 @item @@value@{@var{txivar}@}
18470 Insert the value, if any, of the Texinfo variable @var{txivar},
18471 previously defined by @code{@@set}. @xref{set clear value, ,
18472 @code{@@set} @code{@@clear} @code{@@value}}.
18473
18474 @item @@var@{@var{metasyntactic-variable}@}
18475 Highlight a metasyntactic variable, which is something that stands for
18476 another piece of text. @xref{var, , Indicating Metasyntactic
18477 Variables}.
18478
18479 @item @@verb@{@var{delim} @var{literal} @var{delim}@}
18480 Output @var{literal}, delimited by the single character @var{delim},
18481 exactly as is (in the fixed-width font), including any whitespace or
18482 Texinfo special characters. @xref{verb,,@code{verb}}.
18483
18484 @item @@verbatim
18485 Output the text of the environment exactly as is (in the fixed-width
18486 font). Pair with @code{@@end verbatim}. @xref{verbatim,,@code{verbatim}}.
18487
18488 @item @@verbatiminclude @var{filename}
18489 Output the contents of @var{filename} exactly as is (in the fixed-width font).
18490 @xref{verbatiminclude,,@code{verbatiminclude}}.
18491
18492 @item @@vindex @var{entry}
18493 Add @var{entry} to the index of variables. @xref{Index Entries, ,
18494 Defining the Entries of an Index}.@refill
18495
18496 @item @@vskip @var{amount}
18497 In a printed manual, insert whitespace so as to push text on the
18498 remainder of the page towards the bottom of the page. Used in
18499 formatting the copyright page with the argument @samp{0pt plus
18500 1filll}. (Note spelling of @samp{filll}.) @code{@@vskip} may be used
18501 only in contexts ignored for Info. @xref{Copyright}.
18502
18503 @item @@vtable @var{formatting-command}
18504 Begin a two-column table, using @code{@@item} for each entry.
18505 Automatically enter each of the items in the first column into the
18506 index of variables. Pair with @code{@@end vtable}. The same as
18507 @code{@@table}, except for indexing. @xref{ftable vtable, ,
18508 @code{@@ftable} and @code{@@vtable}}.@refill
18509
18510 @item @@w@{@var{text}@}
18511 Disallow line breaks within @var{text}. @xref{w, , @code{@@w}}.
18512
18513 @item @@xml
18514 Enter XML completely. Pair with @code{@@end xml}. @xref{Raw
18515 Formatter Commands}.
18516
18517 @item @@xref@{@var{node}, [@var{entry}], [@var{node-title}], [@var{info-file}], [@var{manual}]@}
18518 Make a reference that starts with `See' in a printed manual. Follow
18519 command with a punctuation mark. Only the first argument is
18520 mandatory. @xref{xref, , @code{@@xref}}.
18521
18522 @end table
18523
18524
18525 @node Command Syntax
18526 @section @@-Command Syntax
18527 @cindex @@-command syntax
18528 @cindex Syntax, of @@-commands
18529 @cindex Command syntax
18530
18531 The character @samp{@@} is used to start special Texinfo commands.
18532 (It has the same meaning that @samp{\} has in plain @TeX{}.) Texinfo
18533 has four types of @@-command:@refill
18534
18535 @table @asis
18536 @item 1. Non-alphabetic commands.
18537 These commands consist of an @@ followed by a punctuation mark or
18538 other character that is not part of the alphabet. Non-alphabetic
18539 commands are almost always part of the text within a paragraph. The
18540 non-alphabetic commands include @code{@@@@}, @code{@@@{}, @code{@@@}},
18541 @code{@@.}, @code{@@@kbd{SPACE}}, most of the accent commands, and
18542 many more.
18543
18544 @item 2. Alphabetic commands that do not require arguments.
18545 These commands start with @@ followed by a word followed by left- and
18546 right-hand braces. These commands insert special symbols in the
18547 document; they do not require arguments. For example,
18548 @code{@@dots@{@}} @result{} @samp{@dots{}}, @code{@@equiv@{@}}
18549 @result{} @samp{@equiv{}}, @code{@@TeX@{@}} @result{} `@TeX{}',
18550 and @code{@@bullet@{@}} @result{} @samp{@bullet{}}.@refill
18551
18552 @item 3. Alphabetic commands that require arguments within braces.
18553 These commands start with @@ followed by a letter or a word, followed by an
18554 argument within braces. For example, the command @code{@@dfn} indicates
18555 the introductory or defining use of a term; it is used as follows: @samp{In
18556 Texinfo, @@@@-commands are @@dfn@{mark-up@} commands.}@refill
18557
18558 @item 4. Alphabetic commands that occupy an entire line.
18559 These commands occupy an entire line. The line starts with @@,
18560 followed by the name of the command (a word); for example, @code{@@center}
18561 or @code{@@cindex}. If no argument is needed, the word is followed by
18562 the end of the line. If there is an argument, it is separated from
18563 the command name by a space. Braces are not used.@refill
18564 @end table
18565
18566 @cindex Braces and argument syntax
18567 Thus, the alphabetic commands fall into classes that have
18568 different argument syntaxes. You cannot tell to which class a command
18569 belongs by the appearance of its name, but you can tell by the
18570 command's meaning: if the command stands for a glyph, it is in
18571 class 2 and does not require an argument; if it makes sense to use the
18572 command together with other text as part of a paragraph, the command
18573 is in class 3 and must be followed by an argument in braces;
18574 otherwise, it is in class 4 and uses the rest of the line as its
18575 argument.@refill
18576
18577 The purpose of having a different syntax for commands of classes 3 and
18578 4 is to make Texinfo files easier to read, and also to help the GNU
18579 XEmacs paragraph and filling commands work properly. There is only one
18580 exception to this rule: the command @code{@@refill}, which is always
18581 used at the end of a paragraph immediately following the final period
18582 or other punctuation character. @code{@@refill} takes no argument and
18583 does @emph{not} require braces. @code{@@refill} never confuses the
18584 XEmacs paragraph commands because it cannot appear at the beginning of
18585 a line. It is also no longer needed, since all formatters now refill
18586 paragraphs automatically.
18587
18588
18589 @node Tips
18590 @appendix Tips and Hints
18591
18592 Here are some tips for writing Texinfo documentation:@refill
18593
18594 @cindex Tips
18595 @cindex Usage tips
18596 @cindex Hints
18597 @itemize @bullet
18598 @item
18599 Write in the present tense, not in the past or the future.
18600
18601 @item
18602 Write actively! For example, write ``We recommend that @dots{}'' rather
18603 than ``It is recommended that @dots{}''.
18604
18605 @item
18606 Use 70 or 72 as your fill column. Longer lines are hard to read.
18607
18608 @item
18609 Include a copyright notice and copying permissions.
18610 @end itemize
18611
18612 @subsubheading Index, Index, Index!
18613
18614 Write many index entries, in different ways.
18615 Readers like indices; they are helpful and convenient.
18616
18617 Although it is easiest to write index entries as you write the body of
18618 the text, some people prefer to write entries afterwards. In either
18619 case, write an entry before the paragraph to which it applies. This
18620 way, an index entry points to the first page of a paragraph that is
18621 split across pages.
18622
18623 Here are more hints we have found valuable:
18624
18625 @itemize @bullet
18626 @item
18627 Write each index entry differently, so each entry refers to a different
18628 place in the document.
18629
18630 @item
18631 Write index entries only where a topic is discussed significantly. For
18632 example, it is not useful to index ``debugging information'' in a
18633 chapter on reporting bugs. Someone who wants to know about debugging
18634 information will certainly not find it in that chapter.
18635
18636 @item
18637 Consistently capitalize the first word of every concept index entry,
18638 or else consistently use lower case. Terse entries often call for
18639 lower case; longer entries for capitalization. Whichever case
18640 convention you use, please use one or the other consistently! Mixing
18641 the two styles looks bad.
18642
18643 @item
18644 Always capitalize or use upper case for those words in an index for
18645 which this is proper, such as names of countries or acronyms. Always
18646 use the appropriate case for case-sensitive names, such as those in C or
18647 Lisp.
18648
18649 @item
18650 Write the indexing commands that refer to a whole section immediately
18651 after the section command, and write the indexing commands that refer to
18652 a paragraph before that paragraph.
18653
18654 In the example that follows, a blank line comes after the index
18655 entry for ``Leaping'':
18656
18657 @example
18658 @group
18659 @@section The Dog and the Fox
18660 @@cindex Jumping, in general
18661 @@cindex Leaping
18662
18663 @@cindex Dog, lazy, jumped over
18664 @@cindex Lazy dog jumped over
18665 @@cindex Fox, jumps over dog
18666 @@cindex Quick fox jumps over dog
18667 The quick brown fox jumps over the lazy dog.
18668 @end group
18669 @end example
18670
18671 @noindent
18672 (Note that the example shows entries for the same concept that are
18673 written in different ways---@samp{Lazy dog}, and @samp{Dog, lazy}---so
18674 readers can look up the concept in different ways.)
18675 @end itemize
18676
18677 @subsubheading Blank Lines
18678
18679 @itemize @bullet
18680 @item
18681 Insert a blank line between a sectioning command and the first following
18682 sentence or paragraph, or between the indexing commands associated with
18683 the sectioning command and the first following sentence or paragraph, as
18684 shown in the tip on indexing. Otherwise, a formatter may fold title and
18685 paragraph together.
18686
18687 @item
18688 Always insert a blank line before an @code{@@table} command and after an
18689 @code{@@end table} command; but never insert a blank line after an
18690 @code{@@table} command or before an @code{@@end table} command.
18691
18692 @need 1000
18693 For example,
18694
18695 @example
18696 @group
18697 Types of fox:
18698
18699 @@table @@samp
18700 @@item Quick
18701 Jump over lazy dogs.
18702 @end group
18703
18704 @group
18705 @@item Brown
18706 Also jump over lazy dogs.
18707 @@end table
18708
18709 @end group
18710 @group
18711 @@noindent
18712 On the other hand, @dots{}
18713 @end group
18714 @end example
18715
18716 Insert blank lines before and after @code{@@itemize} @dots{} @code{@@end
18717 itemize} and @code{@@enumerate} @dots{} @code{@@end enumerate} in the
18718 same way.
18719 @end itemize
18720
18721 @subsubheading Complete Phrases
18722
18723 Complete phrases are easier to read than @dots{}
18724
18725 @itemize @bullet
18726 @item
18727 Write entries in an itemized list as complete sentences; or at least, as
18728 complete phrases. Incomplete expressions @dots{} awkward @dots{} like
18729 this.
18730
18731 @item
18732 Write the prefatory sentence or phrase for a multi-item list or table as
18733 a complete expression. Do not write ``You can set:''; instead, write
18734 ``You can set these variables:''. The former expression sounds cut off.
18735 @end itemize
18736
18737 @subsubheading Editions, Dates and Versions
18738
18739 Include edition numbers, version numbers, and dates in the
18740 @code{@@copying} text (for people reading the Texinfo file, and for the
18741 legal copyright in the output files). Then use @code{@@insertcopying}
18742 in the @code{@@titlepage} section (for people reading the printed
18743 output) and the Top node (for people reading the online output).
18744
18745 It is easiest to do this using @code{@@set} and @code{@@value}.
18746 @xref{value Example, , @code{@@value} Example}, and @ref{GNU Sample Texts}.
18747
18748
18749 @subsubheading Definition Commands
18750
18751 Definition commands are @code{@@deffn}, @code{@@defun},
18752 @code{@@defmac}, and the like, and enable you to write descriptions in
18753 a uniform format.@refill
18754
18755 @itemize @bullet
18756 @item
18757 Write just one definition command for each entity you define with a
18758 definition command. The automatic indexing feature creates an index
18759 entry that leads the reader to the definition.
18760
18761 @item
18762 Use @code{@@table} @dots{} @code{@@end table} in an appendix that
18763 contains a summary of functions, not @code{@@deffn} or other definition
18764 commands.
18765 @end itemize
18766
18767 @subsubheading Capitalization
18768
18769 @itemize @bullet
18770 @item
18771 Capitalize ``Texinfo''; it is a name. Do not write the @samp{x} or
18772 @samp{i} in upper case.
18773
18774 @item
18775 Capitalize ``Info''; it is a name.
18776
18777 @item
18778 Write @TeX{} using the @code{@@TeX@{@}} command. Note the uppercase
18779 @samp{T} and @samp{X}. This command causes the formatters to
18780 typeset the name according to the wishes of Donald Knuth, who wrote
18781 @TeX{}.
18782 @end itemize
18783
18784 @subsubheading Spaces
18785
18786 Do not use spaces to format a Texinfo file, except inside of
18787 @code{@@example} @dots{} @code{@@end example} and other literal
18788 environments and commands.
18789
18790 @need 700
18791 For example, @TeX{} fills the following:
18792
18793 @example
18794 @group
18795 @@kbd@{C-x v@}
18796 @@kbd@{M-x vc-next-action@}
18797 Perform the next logical operation
18798 on the version-controlled file
18799 corresponding to the current buffer.
18800 @end group
18801 @end example
18802
18803 @need 950
18804 @noindent
18805 so it looks like this:
18806
18807 @iftex
18808 @quotation
18809 @kbd{C-x v}
18810 @kbd{M-x vc-next-action}
18811 Perform the next logical operation on the version-controlled file
18812 corresponding to the current buffer.
18813 @end quotation
18814 @end iftex
18815 @ifnottex
18816 @quotation
18817 `C-x v' `M-x vc-next-action' Perform the next logical operation on the
18818 version-controlled file corresponding to the current buffer.
18819 @end quotation
18820 @end ifnottex
18821
18822 @noindent
18823 In this case, the text should be formatted with
18824 @code{@@table}, @code{@@item}, and @code{@@itemx}, to create a table.
18825
18826
18827 @subsubheading @@code, @@samp, @@var, and @samp{---}
18828
18829 @itemize @bullet
18830 @item
18831 Use @code{@@code} around Lisp symbols, including command names.
18832 For example,
18833
18834 @example
18835 The main function is @@code@{vc-next-action@}, @dots{}
18836 @end example
18837
18838 @item
18839 Avoid putting letters such as @samp{s} immediately after an
18840 @samp{@@code}. Such letters look bad.
18841
18842 @item
18843 Use @code{@@var} around meta-variables. Do not write angle brackets
18844 around them.
18845
18846 @item
18847 Use three hyphens in a row, @samp{---}, to indicate a long dash. @TeX{}
18848 typesets these as a long dash and the Info formatters reduce three
18849 hyphens to two.
18850 @end itemize
18851
18852 @subsubheading Periods Outside of Quotes
18853
18854 Place periods and other punctuation marks @emph{outside} of quotations,
18855 unless the punctuation is part of the quotation. This practice goes
18856 against publishing conventions in the United States, but enables the
18857 reader to distinguish between the contents of the quotation and the
18858 whole passage.
18859
18860 For example, you should write the following sentence with the period
18861 outside the end quotation marks:
18862
18863 @example
18864 Evidently, @samp{au} is an abbreviation for ``author''.
18865 @end example
18866
18867 @noindent
18868 since @samp{au} does @emph{not} serve as an abbreviation for
18869 @samp{author.} (with a period following the word).
18870
18871 @subsubheading Introducing New Terms
18872
18873 @itemize @bullet
18874 @item
18875 Introduce new terms so that a reader who does not know them can
18876 understand them from context; or write a definition for the term.
18877
18878 For example, in the following, the terms ``check in'', ``register'' and
18879 ``delta'' are all appearing for the first time; the example sentence should be
18880 rewritten so they are understandable.
18881
18882 @quotation
18883 The major function assists you in checking in a file to your
18884 version control system and registering successive sets of changes to
18885 it as deltas.
18886 @end quotation
18887
18888 @item
18889 Use the @code{@@dfn} command around a word being introduced, to indicate
18890 that the reader should not expect to know the meaning already, and
18891 should expect to learn the meaning from this passage.
18892 @end itemize
18893
18894 @subsubheading @@pxref
18895
18896 @c !!! maybe include this in the tips on pxref
18897 @ignore
18898 By the way, it is okay to use pxref with something else in front of
18899 it within the parens, as long as the pxref is followed by the close
18900 paren, and the material inside the parens is not part of a larger
18901 sentence. Also, you can use xref inside parens as part of a complete
18902 sentence so long as you terminate the cross reference with punctuation.
18903 @end ignore
18904 Absolutely never use @code{@@pxref} except in the special context for
18905 which it is designed: inside parentheses, with the closing parenthesis
18906 following immediately after the closing brace. One formatter
18907 automatically inserts closing punctuation and the other does not. This
18908 means that the output looks right both in printed output and in an Info
18909 file, but only when the command is used inside parentheses.
18910
18911 @subsubheading Invoking from a Shell
18912
18913 You can invoke programs such as XEmacs, GCC, and @code{gawk} from a
18914 shell. The documentation for each program should contain a section that
18915 describes this. Unfortunately, if the node names and titles for these
18916 sections are all different, they are difficult for users to find.
18917
18918 So, there is a convention to name such sections with a phrase beginning
18919 with the word `Invoking', as in `Invoking XEmacs'; this way, users can
18920 find the section easily.
18921
18922
18923 @subsubheading ANSI C Syntax
18924
18925 When you use @code{@@example} to describe a C function's calling
18926 conventions, use the ANSI C syntax, like this:@refill
18927
18928 @example
18929 void dld_init (char *@@var@{path@});
18930 @end example
18931
18932 @noindent
18933 And in the subsequent discussion, refer to the argument values by
18934 writing the same argument names, again highlighted with
18935 @code{@@var}.@refill
18936
18937 @need 800
18938 Avoid the obsolete style that looks like this:@refill
18939
18940 @example
18941 #include <dld.h>
18942
18943 dld_init (path)
18944 char *path;
18945 @end example
18946
18947 Also, it is best to avoid writing @code{#include} above the
18948 declaration just to indicate that the function is declared in a
18949 header file. The practice may give the misimpression that the
18950 @code{#include} belongs near the declaration of the function. Either
18951 state explicitly which header file holds the declaration or, better
18952 yet, name the header file used for a group of functions at the
18953 beginning of the section that describes the functions.@refill
18954
18955 @subsubheading Bad Examples
18956
18957 Here are several examples of bad writing to avoid:
18958
18959 In this example, say, `` @dots{} you must @code{@@dfn}@{check
18960 in@} the new version.'' That flows better.
18961
18962 @quotation
18963 When you are done editing the file, you must perform a
18964 @code{@@dfn}@{check in@}.
18965 @end quotation
18966
18967 In the following example, say, ``@dots{} makes a unified interface such as VC
18968 mode possible.''
18969
18970 @quotation
18971 SCCS, RCS and other version-control systems all perform similar
18972 functions in broadly similar ways (it is this resemblance which makes
18973 a unified control mode like this possible).
18974 @end quotation
18975
18976 And in this example, you should specify what `it' refers to:
18977
18978 @quotation
18979 If you are working with other people, it assists in coordinating
18980 everyone's changes so they do not step on each other.
18981 @end quotation
18982
18983 @subsubheading And Finally @dots{}
18984
18985 @itemize @bullet
18986 @item
18987 Pronounce @TeX{} as if the @samp{X} were a Greek `chi', as the last
18988 sound in the name `Bach'. But pronounce Texinfo as in `speck':
18989 ``teckinfo''.
18990
18991 @item
18992 Write notes for yourself at the very end of a Texinfo file after the
18993 @code{@@bye}. None of the formatters process text after the
18994 @code{@@bye}; it is as if the text were within @code{@@ignore} @dots{}
18995 @code{@@end ignore}.
18996 @end itemize
18997
18998
18999 @node Sample Texinfo Files
19000 @appendix Sample Texinfo Files
19001 @cindex Sample Texinfo files
19002
19003 The first example is from the first chapter (@pxref{Short Sample}),
19004 given here in its entirety, without commentary. The second
19005 includes the full texts to be used in GNU manuals.
19006
19007 @menu
19008 * Short Sample Texinfo File::
19009 * GNU Sample Texts::
19010 * Verbatim Copying License::
19011 * All-permissive Copying License::
19012 @end menu
19013
19014
19015 @node Short Sample Texinfo File
19016 @section Short Sample
19017 @cindex Sample Texinfo file, no comments
19018
19019 Here is a complete, short sample Texinfo file, without any commentary.
19020 You can see this file, with comments, in the first chapter. @xref{Short
19021 Sample}.
19022
19023 In a nutshell: The @command{makeinfo} program transforms a Texinfo
19024 source file such as this into an Info file or HTML; and @TeX{} typesets
19025 it for a printed manual.
19026
19027
19028 @sp 1
19029 @example
19030 \input texinfo @@c -*-texinfo-*-
19031 @@c %**start of header
19032 @@setfilename sample.info
19033 @@settitle Sample Manual 1.0
19034 @@c %**end of header
19035
19036 @@copying
19037 This is a short example of a complete Texinfo file.
19038
19039 Copyright @copyright{} 2005 Free Software Foundation, Inc.
19040 @@end copying
19041
19042 @@titlepage
19043 @@title Sample Title
19044 @@page
19045 @@vskip 0pt plus 1filll
19046 @@insertcopying
19047 @@end titlepage
19048
19049 @@c Output the table of the contents at the beginning.
19050 @@contents
19051
19052 @@ifnottex
19053 @@node Top
19054 @@top GNU Sample
19055
19056 @@insertcopying
19057 @@end ifnottex
19058
19059 @@menu
19060 * First Chapter:: The first chapter is the
19061 only chapter in this sample.
19062 * Index:: Complete index.
19063 @@end menu
19064
19065
19066 @@node First Chapter
19067 @@chapter First Chapter
19068
19069 @@cindex chapter, first
19070
19071 This is the first chapter.
19072 @@cindex index entry, another
19073
19074 Here is a numbered list.
19075
19076 @@enumerate
19077 @@item
19078 This is the first item.
19079
19080 @@item
19081 This is the second item.
19082 @@end enumerate
19083
19084
19085 @@node Index
19086 @@unnumbered Index
19087
19088 @@printindex cp
19089
19090 @@bye
19091 @end example
19092
19093
19094 @node GNU Sample Texts
19095 @section GNU Sample Texts
19096
19097 @cindex GNU sample texts
19098 @cindex Sample texts, GNU
19099 @cindex Full texts, GNU
19100
19101 Following is a sample Texinfo document with the full texts that should
19102 be used in GNU manuals.
19103
19104 As well as the legal texts, it also serves as a practical example of how
19105 many elements in a GNU system can affect the manual. If you're not
19106 familiar with all these different elements, don't worry. They're not
19107 required and a perfectly good manual can be written without them.
19108 They're included here nonetheless because many manuals do (or could)
19109 benefit from them.
19110
19111 @xref{Short Sample}, for a minimal example of a Texinfo file.
19112 @xref{Beginning a File}, for a full explanation of that minimal
19113 example.
19114
19115 Here are some notes on the example:
19116
19117 @itemize @bullet
19118 @item
19119 @cindex $Id
19120 @cindex CVS $Id
19121 @cindex RCS $Id
19122 @cindex Documentation identification
19123 @cindex Identification of documentation
19124 The @samp{$Id:} comment is for the CVS (@pxref{Top,, Overview, cvs,
19125 Concurrent Versions System}) or RCS
19126 (@url{http://www.gnu.org/software/rcs}) version control systems, which
19127 expand it into a string such as:
19128 @example
19129 $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
19130 @end example
19131 (This is useful in all sources that use version control, not just manuals.)
19132 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
19133 text, if you want a completely unambiguous reference to the
19134 documentation version.
19135
19136 If you want to literally write @t{@w{$}Id$}, use @code{@@w}:
19137 @code{@@w@{$@}Id$}. Unfortunately, this technique does not currently
19138 work in plain text output, since it's not clear what should be done.
19139 We hope to find a solution in a future release.
19140
19141 @item
19142 @pindex automake@r{, and version info}
19143 @vindex UPDATED @r{Automake variable}
19144 @vindex VERSION @r{Automake variable}
19145 @pindex time-stamp.el
19146 The @file{version.texi} in the @code{@@include} command is maintained
19147 automatically by Automake (@pxref{Top,, Introduction, automake, GNU
19148 Automake}). It sets the @samp{VERSION} and @samp{UPDATED} values used
19149 elsewhere. If your distribution doesn't use Automake, but you do use
19150 XEmacs, you may find the time-stamp.el package helpful (@pxref{Time
19151 Stamps,,,xemacs,XEmacs User's Manual}).
19152
19153 @item
19154 The @code{@@syncodeindex} command reflects the recommendation to use
19155 only one index where possible, to make it easier for readers to look up
19156 index entries.
19157
19158 @item
19159 The @code{@@dircategory} is for constructing the Info directory.
19160 @xref{Installing Dir Entries}, which includes a variety of recommended
19161 category names.
19162
19163 @item
19164 The `Invoking' node is a GNU standard to help users find the basic
19165 information about command-line usage of a given program. @xref{Manual
19166 Structure Details,,,standards, GNU Coding Standards}.
19167
19168 @item
19169 @cindex GNU Free Documentation License, including entire
19170 @cindex Free Documentation License, including entire
19171 It is best to include the entire GNU Free Documentation License in a GNU
19172 manual, unless the manual is only a few pages long. Of course this
19173 sample is even shorter than that, but it includes the FDL anyway in
19174 order to show one conventional way to do so. The @file{fdl.texi} file
19175 is available on the GNU machines and in the Texinfo and other GNU
19176 source distributions.
19177
19178 The FDL provides for omitting itself under certain conditions, but in
19179 that case the sample texts given here have to be modified. @xref{GNU
19180 Free Documentation License}.
19181
19182 @item
19183 If the FSF is not the copyright holder, then use the appropriate name.
19184
19185 @item
19186 If your manual is not published on paper by the FSF, then omit the
19187 last sentence in the Back-Cover Text that talks about copies from GNU
19188 Press.
19189
19190 @item
19191 If your manual has Invariant Sections (again, see the license itself
19192 for details), then change the text here accordingly.
19193
19194 @item
19195 For documents that express your personal views, feelings or experiences,
19196 it is more appropriate to use a license permitting only verbatim
19197 copying, rather than the FDL. @xref{Verbatim Copying License}.
19198
19199 @end itemize
19200
19201 Here is the sample document:
19202
19203 @verbatim
19204 \input texinfo @c -*-texinfo-*-
19205 @comment $Id: texinfo.txi,v 1.225 2008/09/07 22:47:46 karl Exp $
19206 @comment %**start of header
19207 @setfilename sample.info
19208 @include version.texi
19209 @settitle GNU Sample @value{VERSION}
19210 @syncodeindex pg cp
19211 @comment %**end of header
19212 @copying
19213 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}),
19214 which is an example in the Texinfo documentation.
19215
19216 Copyright @copyright{} 2007 Free Software Foundation, Inc.
19217
19218 @quotation
19219 Permission is granted to copy, distribute and/or modify this document
19220 under the terms of the GNU Free Documentation License, Version 1.2 or
19221 any later version published by the Free Software Foundation; with no
19222 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
19223 and with the Back-Cover Texts as in (a) below. A copy of the
19224 license is included in the section entitled ``GNU Free Documentation
19225 License.''
19226
19227 (a) The FSF's Back-Cover Text is: ``You have the freedom to
19228 copy and modify this GNU manual. Buying copies from the FSF
19229 supports it in developing GNU and promoting software freedom.''
19230 @end quotation
19231 @end copying
19232
19233 @dircategory Texinfo documentation system
19234 @direntry
19235 * sample: (sample)Invoking sample.
19236 @end direntry
19237
19238 @titlepage
19239 @title GNU Sample
19240 @subtitle for version @value{VERSION}, @value{UPDATED}
19241 @author A.U. Thor (@email{bug-texinfo@@gnu.org})
19242 @page
19243 @vskip 0pt plus 1filll
19244 @insertcopying
19245 @end titlepage
19246
19247 @contents
19248
19249 @ifnottex
19250 @node Top
19251 @top GNU Sample
19252
19253 This manual is for GNU Sample (version @value{VERSION}, @value{UPDATED}).
19254 @end ifnottex
19255
19256 @menu
19257 * Invoking sample::
19258 * Copying This Manual::
19259 * Index::
19260 @end menu
19261
19262
19263 @node Invoking sample
19264 @chapter Invoking sample
19265
19266 @pindex sample
19267 @cindex invoking @command{sample}
19268
19269 This is a sample manual. There is no sample program to
19270 invoke, but if there was, you could see its basic usage
19271 and command line options here.
19272
19273
19274 @node GNU Free Documentation License
19275 @appendix GNU Free Documentation License
19276
19277 @include fdl.texi
19278
19279
19280 @node Index
19281 @unnumbered Index
19282
19283 @printindex cp
19284
19285 @bye
19286 @end verbatim
19287
19288
19289 @node Verbatim Copying License
19290 @section Verbatim Copying License
19291
19292 @cindex Verbatim copying license
19293 @cindex License for verbatim copying
19294
19295 For software manuals and other documentation, it is important to use a
19296 license permitting free redistribution and updating, so that when a free
19297 program is changed, the documentation can be updated as well.
19298
19299 On the other hand, for documents that express your personal views,
19300 feelings or experiences, it is more appropriate to use a license
19301 permitting only verbatim copying.
19302
19303 Here is sample text for such a license permitting verbatim copying only.
19304 This is just the license text itself. For a complete sample document,
19305 see the previous sections.
19306
19307 @verbatim
19308 @copying
19309 This document is a sample for allowing verbatim copying only.
19310
19311 Copyright @copyright{} 2005 Free Software Foundation, Inc.
19312
19313 @quotation
19314 Permission is granted to make and distribute verbatim copies
19315 of this entire document without royalty provided the
19316 copyright notice and this permission notice are preserved.
19317 @end quotation
19318 @end copying
19319 @end verbatim
19320
19321
19322 @node All-permissive Copying License
19323 @section All-permissive Copying License
19324
19325 @cindex All-permissive copying license
19326 @cindex License for all-permissive copying
19327
19328 For software manuals and other documentation, it is important to use a
19329 license permitting free redistribution and updating, so that when a free
19330 program is changed, the documentation can be updated as well.
19331
19332 On the other hand, for small supporting files, short manuals (under 300
19333 lines long) and rough documentation (README files, INSTALL files, etc.),
19334 the full FDL would be overkill. They can use a simple all-permissive
19335 license.
19336
19337 Here is sample text for such an all-permissive license. This is just
19338 the license text itself. For a complete sample document, see the
19339 previous sections.
19340
19341 @example
19342 Copyright @copyright{} 2005 Free Software Foundation, Inc.
19343
19344 Copying and distribution of this file, with or without modification,
19345 are permitted in any medium without royalty provided the copyright
19346 notice and this notice are preserved.
19347 @end example
19348
19349
19350 @node Include Files
19351 @appendix Include Files
19352 @cindex Include files
19353
19354 When @TeX{} or an Info formatting command sees an @code{@@include}
19355 command in a Texinfo file, it processes the contents of the file named
19356 by the command and incorporates them into the DVI or Info file being
19357 created. Index entries from the included file are incorporated into
19358 the indices of the output file.
19359
19360 Include files let you keep a single large document as a collection of
19361 conveniently small parts.
19362
19363 @menu
19364 * Using Include Files:: How to use the @code{@@include} command.
19365 * texinfo-multiple-files-update:: How to create and update nodes and
19366 menus when using included files.
19367 * Include Files Requirements:: @code{texinfo-multiple-files-update} needs.
19368 * Sample Include File:: A sample outer file with included files
19369 within it; and a sample included file.
19370 * Include Files Evolution:: How use of the @code{@@include} command
19371 has changed over time.
19372 @end menu
19373
19374 @node Using Include Files
19375 @section How to Use Include Files
19376 @findex include
19377
19378 To include another file within a Texinfo file, write the
19379 @code{@@include} command at the beginning of a line and follow it on
19380 the same line by the name of a file to be included. For example:
19381
19382 @example
19383 @@include buffers.texi
19384 @end example
19385
19386 The name of the file is taken literally, with a single exception:
19387 @code{@@value@{@var{var}@}} references are expanded. This makes it
19388 possible to reliably include files in other directories in a
19389 distribution. @xref{verbatiminclude,,@code{@@verbatiminclude}}, for
19390 an example.
19391
19392 An included file should simply be a segment of text that you expect to
19393 be included as is into the overall or @dfn{outer} Texinfo file; it
19394 should not contain the standard beginning and end parts of a Texinfo
19395 file. In particular, you should not start an included file with a
19396 line saying @samp{\input texinfo}; if you do, that phrase is inserted
19397 into the output file as is. Likewise, you should not end an included
19398 file with an @code{@@bye} command; nothing after @code{@@bye} is
19399 formatted.
19400
19401 In the past, you were required to write an @code{@@setfilename} line at the
19402 beginning of an included file, but no longer. Now, it does not matter
19403 whether you write such a line. If an @code{@@setfilename} line exists
19404 in an included file, it is ignored.@refill
19405
19406 Conventionally, an included file begins with an @code{@@node} line that
19407 is followed by an @code{@@chapter} line. Each included file is one
19408 chapter. This makes it easy to use the regular node and menu creating
19409 and updating commands to create the node pointers and menus within the
19410 included file. However, the simple XEmacs node and menu creating and
19411 updating commands do not work with multiple Texinfo files. Thus you
19412 cannot use these commands to fill in the `Next', `Previous', and `Up'
19413 pointers of the @code{@@node} line that begins the included file. Also,
19414 you cannot use the regular commands to create a master menu for the
19415 whole file. Either you must insert the menus and the `Next',
19416 `Previous', and `Up' pointers by hand, or you must use the XEmacs
19417 Texinfo mode command, @code{texinfo-multiple-files-update}, that is
19418 designed for @code{@@include} files.@refill
19419
19420 When an included file does not have any node lines in it, the
19421 multiple files update command does not try to create a menu entry
19422 for it. Consequently, you can include any file, such as a
19423 version or an update file without node lines, not just files that
19424 are chapters. Small includable files like this are created by
19425 Automake (@pxref{GNU Sample Texts}).
19426
19427
19428 @node texinfo-multiple-files-update
19429 @section @code{texinfo-multiple-files-update}
19430 @findex texinfo-multiple-files-update
19431
19432 XEmacs Texinfo mode provides the @code{texinfo-multiple-files-update}
19433 command. This command creates or updates `Next', `Previous', and `Up'
19434 pointers of included files as well as those in the outer or overall
19435 Texinfo file, and it creates or updates a main menu in the outer file.
19436 Depending whether you call it with optional arguments, the command
19437 updates only the pointers in the first @code{@@node} line of the
19438 included files or all of them:@refill
19439
19440 @table @kbd
19441 @item M-x texinfo-multiple-files-update
19442 Called without any arguments:@refill
19443
19444 @itemize @minus
19445 @item
19446 Create or update the `Next', `Previous', and `Up' pointers of the
19447 first @code{@@node} line in each file included in an outer or overall
19448 Texinfo file.@refill
19449
19450 @item
19451 Create or update the `Top' level node pointers of the outer or
19452 overall file.@refill
19453
19454 @item
19455 Create or update a main menu in the outer file.@refill
19456 @end itemize
19457
19458 @item C-u M-x texinfo-multiple-files-update
19459 Called with @kbd{C-u} as a prefix argument:
19460
19461 @itemize @minus{}
19462 @item
19463 Create or update pointers in the first @code{@@node} line in each
19464 included file.
19465
19466 @item
19467 Create or update the `Top' level node pointers of the outer file.
19468
19469 @item
19470 Create and insert a master menu in the outer file. The master menu
19471 is made from all the menus in all the included files.@refill
19472 @end itemize
19473
19474 @item C-u 8 M-x texinfo-multiple-files-update
19475 Called with a numeric prefix argument, such as @kbd{C-u 8}:
19476
19477 @itemize @minus
19478 @item
19479 Create or update @strong{all} the `Next', `Previous', and `Up' pointers
19480 of all the included files.@refill
19481
19482 @item
19483 Create or update @strong{all} the menus of all the included
19484 files.@refill
19485
19486 @item
19487 Create or update the `Top' level node pointers of the outer or
19488 overall file.@refill
19489
19490 @item
19491 And then create a master menu in the outer file. This is similar to
19492 invoking @code{texinfo-master-menu} with an argument when you are
19493 working with just one file.@refill
19494 @end itemize
19495 @end table
19496
19497 Note the use of the prefix argument in interactive use: with a regular
19498 prefix argument, just @w{@kbd{C-u}}, the
19499 @code{texinfo-multiple-files-update} command inserts a master menu;
19500 with a numeric prefix argument, such as @kbd{C-u 8}, the command
19501 updates @strong{every} pointer and menu in @strong{all} the files and then inserts a
19502 master menu.@refill
19503
19504
19505 @node Include Files Requirements
19506 @section Include Files Requirements
19507 @cindex Include files requirements
19508 @cindex Requirements for include files
19509
19510 If you plan to use the @code{texinfo-multiple-files-update} command,
19511 the outer Texinfo file that lists included files within it should
19512 contain nothing but the beginning and end parts of a Texinfo file, and
19513 a number of @code{@@include} commands listing the included files. It
19514 should not even include indices, which should be listed in an included
19515 file of their own.@refill
19516
19517 Moreover, each of the included files must contain exactly one highest
19518 level node (conventionally, @code{@@chapter} or equivalent),
19519 and this node must be the first node in the included file.
19520 Furthermore, each of these highest level nodes in each included file
19521 must be at the same hierarchical level in the file structure.
19522 Usually, each is an @code{@@chapter}, an @code{@@appendix}, or an
19523 @code{@@unnumbered} node. Thus, normally, each included file contains
19524 one, and only one, chapter or equivalent-level node.@refill
19525
19526 The outer file should contain only @emph{one} node, the `Top' node. It
19527 should @emph{not} contain any nodes besides the single `Top' node. The
19528 @code{texinfo-multiple-files-update} command will not process
19529 them.@refill
19530
19531
19532 @node Sample Include File
19533 @section Sample File with @code{@@include}
19534 @cindex Sample @code{@@include} file
19535 @cindex Include file sample
19536 @cindex @code{@@include} file sample
19537
19538 Here is an example of an outer Texinfo file with @code{@@include} files
19539 within it before running @code{texinfo-multiple-files-update}, which
19540 would insert a main or master menu:
19541
19542 @example
19543 @group
19544 \input texinfo @@c -*-texinfo-*-
19545 @c %**start of header
19546 @@setfilename include-example.info
19547 @@settitle Include Example
19548 @c %**end of header
19549 @end group
19550
19551 ... @xref{Sample Texinfo Files}, for
19552 examples of the rest of the frontmatter ...
19553
19554 @group
19555 @@ifnottex
19556 @@node Top
19557 @@top Include Example
19558 @@end ifnottex
19559 @end group
19560
19561 @group
19562 @@include foo.texinfo
19563 @@include bar.texinfo
19564 @@include concept-index.texinfo
19565 @@bye
19566 @end group
19567 @end example
19568
19569 An included file, such as @file{foo.texinfo}, might look like this:
19570
19571 @example
19572 @group
19573 @@node First
19574 @@chapter First Chapter
19575
19576 Contents of first chapter @dots{}
19577 @end group
19578 @end example
19579
19580 The full contents of @file{concept-index.texinfo} might be as simple as this:
19581
19582 @example
19583 @group
19584 @@node Concept Index
19585 @@unnumbered Concept Index
19586
19587 @@printindex cp
19588 @end group
19589 @end example
19590
19591 The outer Texinfo source file for @cite{The XEmacs Lisp Reference
19592 Manual} is named @file{elisp.texi}. This outer file contains a master
19593 menu with 417 entries and a list of 41 @code{@@include}
19594 files.
19595
19596
19597 @node Include Files Evolution
19598 @section Evolution of Include Files
19599
19600 When Info was first created, it was customary to create many small
19601 Info files on one subject. Each Info file was formatted from its own
19602 Texinfo source file. This custom meant that XEmacs did not need to
19603 make a large buffer to hold the whole of a large Info file when
19604 someone wanted information; instead, XEmacs allocated just enough
19605 memory for the small Info file that contained the particular
19606 information sought. This way, XEmacs could avoid wasting memory.@refill
19607
19608 References from one file to another were made by referring to the file
19609 name as well as the node name. (@xref{Other Info Files, , Referring to
19610 Other Info Files}. Also, see @ref{Four and Five Arguments, ,
19611 @code{@@xref} with Four and Five Arguments}.)@refill
19612
19613 Include files were designed primarily as a way to create a single,
19614 large printed manual out of several smaller Info files. In a printed
19615 manual, all the references were within the same document, so @TeX{}
19616 could automatically determine the references' page numbers. The Info
19617 formatting commands used include files only for creating joint
19618 indices; each of the individual Texinfo files had to be formatted for
19619 Info individually. (Each, therefore, required its own
19620 @code{@@setfilename} line.)@refill
19621
19622 However, because large Info files are now split automatically, it is
19623 no longer necessary to keep them small.@refill
19624
19625 Nowadays, multiple Texinfo files are used mostly for large documents,
19626 such as @cite{The XEmacs Lisp Reference Manual}, and for projects
19627 in which several different people write different sections of a
19628 document simultaneously.@refill
19629
19630 In addition, the Info formatting commands have been extended to work
19631 with the @code{@@include} command so as to create a single large Info
19632 file that is split into smaller files if necessary. This means that
19633 you can write menus and cross references without naming the different
19634 Texinfo files.@refill
19635
19636
19637 @node Headings
19638 @appendix Page Headings
19639 @cindex Headings
19640 @cindex Footings
19641 @cindex Page numbering
19642 @cindex Page headings
19643 @cindex Formatting headings and footings
19644
19645 Most printed manuals contain headings along the top of every page
19646 except the title and copyright pages. Some manuals also contain
19647 footings. (Headings and footings have no meaning to Info, which is
19648 not paginated.)@refill
19649
19650 @menu
19651 * Headings Introduced:: Conventions for using page headings.
19652 * Heading Format:: Standard page heading formats.
19653 * Heading Choice:: How to specify the type of page heading.
19654 * Custom Headings:: How to create your own headings and footings.
19655 @end menu
19656
19657 @node Headings Introduced
19658 @section Headings Introduced
19659
19660 Texinfo provides standard page heading formats for manuals that are
19661 printed on one side of each sheet of paper and for manuals that are
19662 printed on both sides of the paper. Typically, you will use these
19663 formats, but you can specify your own format if you wish.@refill
19664
19665 In addition, you can specify whether chapters should begin on a new
19666 page, or merely continue the same page as the previous chapter; and if
19667 chapters begin on new pages, you can specify whether they must be
19668 odd-numbered pages.@refill
19669
19670 By convention, a book is printed on both sides of each sheet of paper.
19671 When you open a book, the right-hand page is odd-numbered, and
19672 chapters begin on right-hand pages---a preceding left-hand page is
19673 left blank if necessary. Reports, however, are often printed on just
19674 one side of paper, and chapters begin on a fresh page immediately
19675 following the end of the preceding chapter. In short or informal
19676 reports, chapters often do not begin on a new page at all, but are
19677 separated from the preceding text by a small amount of whitespace.@refill
19678
19679 The @code{@@setchapternewpage} command controls whether chapters begin
19680 on new pages, and whether one of the standard heading formats is used.
19681 In addition, Texinfo has several heading and footing commands that you
19682 can use to generate your own heading and footing formats.@refill
19683
19684 In Texinfo, headings and footings are single lines at the tops and
19685 bottoms of pages; you cannot create multiline headings or footings.
19686 Each header or footer line is divided into three parts: a left part, a
19687 middle part, and a right part. Any part, or a whole line, may be left
19688 blank. Text for the left part of a header or footer line is set
19689 flushleft; text for the middle part is centered; and, text for the
19690 right part is set flushright.@refill
19691
19692 @node Heading Format
19693 @comment node-name, next, previous, up
19694 @section Standard Heading Formats
19695
19696 Texinfo provides two standard heading formats, one for manuals printed
19697 on one side of each sheet of paper, and the other for manuals printed
19698 on both sides of the paper.
19699
19700 By default, nothing is specified for the footing of a Texinfo file,
19701 so the footing remains blank.@refill
19702
19703 The standard format for single-sided printing consists of a header
19704 line in which the left-hand part contains the name of the chapter, the
19705 central part is blank, and the right-hand part contains the page
19706 number.@refill
19707
19708 @need 950
19709 A single-sided page looks like this:
19710
19711 @example
19712 @group
19713 _______________________
19714 | |
19715 | chapter page number |
19716 | |
19717 | Start of text ... |
19718 | ... |
19719 | |
19720 @end group
19721 @end example
19722
19723 The standard format for two-sided printing depends on whether the page
19724 number is even or odd. By convention, even-numbered pages are on the
19725 left- and odd-numbered pages are on the right. (@TeX{} will adjust the
19726 widths of the left- and right-hand margins. Usually, widths are
19727 correct, but during double-sided printing, it is wise to check that
19728 pages will bind properly---sometimes a printer will produce output in
19729 which the even-numbered pages have a larger right-hand margin than the
19730 odd-numbered pages.)@refill
19731
19732 In the standard double-sided format, the left part of the left-hand
19733 (even-numbered) page contains the page number, the central part is
19734 blank, and the right part contains the title (specified by the
19735 @code{@@settitle} command). The left part of the right-hand
19736 (odd-numbered) page contains the name of the chapter, the central part
19737 is blank, and the right part contains the page number.@refill
19738
19739 @need 750
19740 Two pages, side by side as in an open book, look like this:@refill
19741
19742 @example
19743 @group
19744 _______________________ _______________________
19745 | | | |
19746 | page number title | | chapter page number |
19747 | | | |
19748 | Start of text ... | | More text ... |
19749 | ... | | ... |
19750 | | | |
19751 @end group
19752 @end example
19753
19754 @noindent
19755 The chapter name is preceded by the word ``Chapter'', the chapter number
19756 and a colon. This makes it easier to keep track of where you are in the
19757 manual.@refill
19758
19759 @node Heading Choice
19760 @comment node-name, next, previous, up
19761 @section Specifying the Type of Heading
19762
19763 @TeX{} does not begin to generate page headings for a standard Texinfo
19764 file until it reaches the @code{@@end titlepage} command. Thus, the
19765 title and copyright pages are not numbered. The @code{@@end
19766 titlepage} command causes @TeX{} to begin to generate page headings
19767 according to a standard format specified by the
19768 @code{@@setchapternewpage} command that precedes the
19769 @code{@@titlepage} section.@refill
19770
19771 @need 1000
19772 There are four possibilities:@refill
19773
19774 @table @asis
19775 @item No @code{@@setchapternewpage} command
19776 Cause @TeX{} to specify the single-sided heading format, with chapters
19777 on new pages. This is the same as @code{@@setchapternewpage on}.@refill
19778
19779 @item @code{@@setchapternewpage on}
19780 Specify the single-sided heading format, with chapters on new pages.@refill
19781
19782 @item @code{@@setchapternewpage off}
19783 Cause @TeX{} to start a new chapter on the same page as the last page of
19784 the preceding chapter, after skipping some vertical whitespace. Also
19785 cause @TeX{} to typeset for single-sided printing. (You can override
19786 the headers format with the @code{@@headings double} command; see
19787 @ref{headings on off, , The @code{@@headings} Command}.)@refill
19788
19789 @item @code{@@setchapternewpage odd}
19790 Specify the double-sided heading format, with chapters on new pages.@refill
19791 @end table
19792
19793 @noindent
19794 Texinfo lacks an @code{@@setchapternewpage even} command.@refill
19795
19796 @node Custom Headings
19797 @comment node-name, next, previous, up
19798 @section How to Make Your Own Headings
19799
19800 You can use the standard headings provided with Texinfo or specify
19801 your own. By default, Texinfo has no footers, so if you specify them,
19802 the available page size for the main text will be slightly reduced.
19803
19804 Texinfo provides six commands for specifying headings and
19805 footings:
19806 @itemize @bullet
19807 @item
19808 @code{@@everyheading} @code{@@everyfooting} generate page headers and
19809 footers that are the same for both even- and odd-numbered pages.
19810 @item
19811 @code{@@evenheading} and @code{@@evenfooting} command generate headers
19812 and footers for even-numbered (left-hand) pages.
19813 @item
19814 @code{@@oddheading} and @code{@@oddfooting} generate headers and footers
19815 for odd-numbered (right-hand) pages.
19816 @end itemize
19817
19818 Write custom heading specifications in the Texinfo file immediately
19819 after the @code{@@end titlepage} command.
19820 You must cancel the predefined heading commands with the
19821 @code{@@headings off} command before defining your own
19822 specifications.
19823
19824 @need 1000
19825 Here is how to tell @TeX{} to place the chapter name at the left, the
19826 page number in the center, and the date at the right of every header
19827 for both even- and odd-numbered pages:
19828
19829 @example
19830 @group
19831 @@headings off
19832 @@everyheading @@thischapter @@| @@thispage @@| @@today@{@}
19833 @end group
19834 @end example
19835
19836 @noindent
19837 You need to divide the left part from the central part and the central
19838 part from the right part by inserting @samp{@@|} between parts.
19839 Otherwise, the specification command will not be able to tell where
19840 the text for one part ends and the next part begins.
19841
19842 Each part can contain text or @@-commands. The text
19843 is printed as if the part were within an ordinary paragraph in the
19844 body of the page. The @@-commands replace
19845 themselves with the page number, date, chapter name, or
19846 whatever.
19847
19848 @need 950
19849 Here are the six heading and footing commands:
19850
19851 @table @code
19852 @item @@everyheading @var{left} @@| @var{center} @@| @var{right}
19853 @itemx @@everyfooting @var{left} @@| @var{center} @@| @var{right}
19854 @findex everyheading
19855 @findex everyfooting
19856 The `every' commands specify the format for both even- and odd-numbered
19857 pages. These commands are for documents that are printed on one side
19858 of each sheet of paper, or for documents in which you want symmetrical
19859 headers or footers.
19860
19861 @item @@evenheading @var{left} @@| @var{center} @@| @var{right}
19862 @itemx @@oddheading @var{left} @@| @var{center} @@| @var{right}
19863 @itemx @@evenfooting @var{left} @@| @var{center} @@| @var{right}
19864 @itemx @@oddfooting @var{left} @@| @var{center} @@| @var{right}
19865 @findex evenheading
19866 @findex evenfooting
19867 @findex oddheading
19868 @findex oddfooting
19869 The `even' and `odd' commands specify the format for even-numbered
19870 pages and odd-numbered pages. These commands are for books and
19871 manuals that are printed on both sides of each sheet of paper.
19872 @end table
19873
19874 Use the @samp{@@this@dots{}} series of @@-commands to
19875 provide the names of chapters
19876 and sections and the page number. You can use the
19877 @samp{@@this@dots{}} commands in the left, center, or right portions
19878 of headers and footers, or anywhere else in a Texinfo file so long as
19879 they are between @code{@@iftex} and @code{@@end iftex} commands.
19880
19881 @need 1000
19882 Here are the @samp{@@this@dots{}} commands:
19883
19884 @table @code
19885 @item @@thispage
19886 @findex thispage
19887 Expands to the current page number.
19888
19889 @item @@thissectionname
19890 @findex thissectionname
19891 Expands to the name of the current section.
19892
19893 @item @@thissectionnum
19894 @findex thissectionnum
19895 Expands to the number of the current section.
19896
19897 @item @@thissection
19898 @findex thissection
19899 Expands to the number and name of the current section, in the format
19900 `Section 1: Title'.
19901
19902 @item @@thischaptername
19903 @findex thischaptername
19904 Expands to the name of the current chapter.
19905
19906 @item @@thischapternum
19907 @findex thischapternum
19908 Expands to the number of the current chapter, or letter of the current
19909 appendix.
19910
19911 @item @@thischapter
19912 @findex thischapter
19913 Expands to the number and name of the current
19914 chapter, in the format `Chapter 1: Title'.
19915
19916 @item @@thistitle
19917 @findex thistitle
19918 Expands to the name of the document, as specified by the
19919 @code{@@settitle} command.
19920
19921 @item @@thisfile
19922 @findex thisfile
19923 For @code{@@include} files only: expands to the name of the current
19924 @code{@@include} file. If the current Texinfo source file is not an
19925 @code{@@include} file, this command has no effect. This command does
19926 @emph{not} provide the name of the current Texinfo source file unless
19927 it is an @code{@@include} file. (@xref{Include Files}, for more
19928 information about @code{@@include} files.)
19929 @end table
19930
19931 @noindent
19932 You can also use the @code{@@today@{@}} command, which expands to the
19933 current date, in `1 Jan 1900' format.
19934 @findex today
19935
19936 Other @@-commands and text are printed in a header or footer just as
19937 if they were in the body of a page. It is useful to incorporate text,
19938 particularly when you are writing drafts:
19939
19940 @example
19941 @group
19942 @@headings off
19943 @@everyheading @@emph@{Draft!@} @@| @@thispage @@| @@thischapter
19944 @@everyfooting @@| @@| Version: 0.27: @@today@{@}
19945 @end group
19946 @end example
19947
19948 Beware of overlong titles: they may overlap another part of the
19949 header or footer and blot it out.
19950
19951 If you have very short chapters and/or sections, several of them can
19952 appear on a single page. You can specify which chapters and sections
19953 you want @code{@@thischapter}, @code{@@thissection} and other such
19954 macros to refer to on such pages as follows:
19955
19956 @table @code
19957 @item @@everyheadingmarks @var{ref}
19958 @itemx @@everyfootingmarks @var{ref}
19959 @findex everyheadingmarks
19960 @findex everyfootingmarks
19961 The @var{ref} argument can be either @code{top} (the @code{@@this...}
19962 commands will refer to the chapter/section at the top of a page) or
19963 @code{bottom} (the commands will reflect the situation at the bottom
19964 of a page). These @samp{@@every...} commands specify what to do on
19965 both even- and odd-numbered pages.
19966
19967 @item @@evenheadingmarks @var{ref}
19968 @itemx @@oddheadingmarks @var{ref}
19969 @itemx @@evenfootingmarks @var{ref}
19970 @itemx @@oddfootingmarks @var{ref}
19971 @findex evenheadingmarks
19972 @findex oddheadingmarks
19973 @findex evenfootingmarks
19974 @findex oddfootingmarks
19975 These @samp{@@even...} and @samp{@@odd...} commands specify what to do
19976 on only even- or odd-numbered pages, respectively. The @var{ref}
19977 argument is the same as with the @samp{@@every...} commands.
19978 @end table
19979
19980 Write these commands immediately after the @code{@@...contents}
19981 commands, or after the @code{@@end titlepage} command if you don't
19982 have a table of contents or if it is printed at the end of your
19983 manual.
19984
19985 By default the @code{@@this...} commands reflect the situation at the
19986 bottom of a page both in headings and in footings.
19987
19988
19989 @node Catching Mistakes
19990 @appendix Formatting Mistakes
19991 @cindex Structure, catching mistakes in
19992 @cindex Nodes, catching mistakes
19993 @cindex Catching mistakes
19994 @cindex Correcting mistakes
19995 @cindex Mistakes, catching
19996 @cindex Problems, catching
19997 @cindex Debugging the Texinfo structure
19998
19999 Besides mistakes in the content of your documentation, there are two
20000 kinds of mistake you can make with Texinfo: you can make mistakes with
20001 @@-commands, and you can make mistakes with the structure of the nodes
20002 and chapters.
20003
20004 XEmacs has two tools for catching the @@-command mistakes and two for
20005 catching structuring mistakes.@refill
20006
20007 For finding problems with @@-commands, you can run @TeX{} or a region
20008 formatting command on the region that has a problem; indeed, you can
20009 run these commands on each region as you write it.@refill
20010
20011 For finding problems with the structure of nodes and chapters, you can use
20012 @kbd{C-c C-s} (@code{texinfo-show-structure}) and the related @code{occur}
20013 command and you can use the @kbd{M-x Info-validate} command.@refill
20014
20015 @menu
20016 * makeinfo Preferred:: @code{makeinfo} finds errors.
20017 * Debugging with Info:: How to catch errors with Info formatting.
20018 * Debugging with TeX:: How to catch errors with @TeX{} formatting.
20019 * Using texinfo-show-structure:: How to use @code{texinfo-show-structure}.
20020 * Using occur:: How to list all lines containing a pattern.
20021 * Running Info-Validate:: How to find badly referenced nodes.
20022 @end menu
20023
20024
20025 @node makeinfo Preferred
20026 @section @code{makeinfo} Find Errors
20027
20028 The @code{makeinfo} program does an excellent job of catching errors
20029 and reporting them---far better than @code{texinfo-format-region} or
20030 @code{texinfo-format-buffer}. In addition, the various functions for
20031 automatically creating and updating node pointers and menus remove
20032 many opportunities for human error.@refill
20033
20034 If you can, use the updating commands to create and insert pointers
20035 and menus. These prevent many errors. Then use @code{makeinfo} (or
20036 its Texinfo mode manifestations, @code{makeinfo-region} and
20037 @code{makeinfo-buffer}) to format your file and check for other
20038 errors. This is the best way to work with Texinfo. But if you
20039 cannot use @code{makeinfo}, or your problem is very puzzling, then you
20040 may want to use the tools described in this appendix.@refill
20041
20042 @node Debugging with Info
20043 @comment node-name, next, previous, up
20044 @section Catching Errors with Info Formatting
20045 @cindex Catching errors with Info formatting
20046 @cindex Debugging with Info formatting
20047
20048 After you have written part of a Texinfo file, you can use the
20049 @code{texinfo-format-region} or the @code{makeinfo-region} command to
20050 see whether the region formats properly.@refill
20051
20052 Most likely, however, you are reading this section because for some
20053 reason you cannot use the @code{makeinfo-region} command; therefore, the
20054 rest of this section presumes that you are using
20055 @code{texinfo-format-region}.@refill
20056
20057 If you have made a mistake with an @@-command,
20058 @code{texinfo-format-region} will stop processing at or after the
20059 error and display an error message. To see where in the buffer the
20060 error occurred, switch to the @samp{*Info Region*} buffer; the cursor
20061 will be in a position that is after the location of the error. Also,
20062 the text will not be formatted after the place where the error
20063 occurred (or more precisely, where it was detected).@refill
20064
20065 For example, if you accidentally end a menu with the command @code{@@end
20066 menus} with an `s' on the end, instead of with @code{@@end menu}, you
20067 will see an error message that says:@refill
20068
20069 @example
20070 @@end menus is not handled by texinfo
20071 @end example
20072
20073 @noindent
20074 The cursor will stop at the point in the buffer where the error
20075 occurs, or not long after it. The buffer will look like this:@refill
20076
20077 @example
20078 @group
20079 ---------- Buffer: *Info Region* ----------
20080 * Menu:
20081
20082 * Using texinfo-show-structure:: How to use
20083 `texinfo-show-structure'
20084 to catch mistakes.
20085 * Running Info-Validate:: How to check for
20086 unreferenced nodes.
20087 @@end menus
20088 @point{}
20089 ---------- Buffer: *Info Region* ----------
20090 @end group
20091 @end example
20092
20093 The @code{texinfo-format-region} command sometimes provides slightly
20094 odd error messages. For example, the following cross reference fails to format:@refill
20095
20096 @example
20097 (@@xref@{Catching Mistakes, for more info.)
20098 @end example
20099
20100 @noindent
20101 In this case, @code{texinfo-format-region} detects the missing closing
20102 brace but displays a message that says @samp{Unbalanced parentheses}
20103 rather than @samp{Unbalanced braces}. This is because the formatting
20104 command looks for mismatches between braces as if they were
20105 parentheses.@refill
20106
20107 Sometimes @code{texinfo-format-region} fails to detect mistakes. For
20108 example, in the following, the closing brace is swapped with the
20109 closing parenthesis:@refill
20110
20111 @example
20112 (@@xref@{Catching Mistakes), for more info.@}
20113 @end example
20114
20115 @noindent
20116 Formatting produces:
20117 @example
20118 (*Note for more info.: Catching Mistakes)
20119 @end example
20120
20121 The only way for you to detect this error is to realize that the
20122 reference should have looked like this:@refill
20123
20124 @example
20125 (*Note Catching Mistakes::, for more info.)
20126 @end example
20127
20128 Incidentally, if you are reading this node in Info and type @kbd{f
20129 @key{RET}} (@code{Info-follow-reference}), you will generate an error
20130 message that says:
20131
20132 @example
20133 No such node: "Catching Mistakes) The only way @dots{}
20134 @end example
20135
20136 @noindent
20137 This is because Info perceives the example of the error as the first
20138 cross reference in this node and if you type a @key{RET} immediately
20139 after typing the Info @kbd{f} command, Info will attempt to go to the
20140 referenced node. If you type @kbd{f catch @key{TAB} @key{RET}}, Info
20141 will complete the node name of the correctly written example and take
20142 you to the `Catching Mistakes' node. (If you try this, you can return
20143 from the `Catching Mistakes' node by typing @kbd{l}
20144 (@code{Info-last}).)
20145
20146 @c !!! section on using Elisp debugger ignored.
20147 @ignore
20148 Sometimes @code{texinfo-format-region} will stop long after the
20149 original error; this is because it does not discover the problem until
20150 then. In this case, you will need to backtrack.@refill
20151
20152 @c menu
20153 @c * Using the XEmacs Lisp Debugger:: How to use the XEmacs Lisp debugger.
20154 @c end menu
20155
20156 @c node Using the XEmacs Lisp Debugger
20157 @c appendixsubsec Using the XEmacs Lisp Debugger
20158 @c index Using the XEmacs Lisp debugger
20159 @c index XEmacs Lisp debugger
20160 @c index Debugger, using the XEmacs Lisp
20161
20162 If an error is especially elusive, you can turn on the XEmacs Lisp
20163 debugger and look at the backtrace; this tells you where in the
20164 @code{texinfo-format-region} function the problem occurred. You can
20165 turn on the debugger with the command:@refill
20166
20167 @example
20168 M-x set-variable @key{RET} debug-on-error @key{RET} t @key{RET}
20169 @end example
20170
20171 @noindent
20172 and turn it off with
20173
20174 @example
20175 M-x set-variable @key{RET} debug-on-error @key{RET} nil @key{RET}
20176 @end example
20177
20178 Often, when you are using the debugger, it is easier to follow what is
20179 going on if you use the XEmacs Lisp files that are not byte-compiled.
20180 The byte-compiled sources send octal numbers to the debugger that may
20181 look mysterious. To use the uncompiled source files, load
20182 @file{texinfmt.el} and @file{texinfo.el} with the @kbd{M-x load-file}
20183 command.@refill
20184
20185 The debugger will not catch an error if @code{texinfo-format-region}
20186 does not detect one. In the example shown above,
20187 @code{texinfo-format-region} did not find the error when the whole
20188 list was formatted, but only when part of the list was formatted.
20189 When @code{texinfo-format-region} did not find an error, the debugger
20190 did not find one either. @refill
20191
20192 However, when @code{texinfo-format-region} did report an error, it
20193 invoked the debugger. This is the backtrace it produced:@refill
20194
20195 @example
20196 ---------- Buffer: *Backtrace* ----------
20197 Signalling: (search-failed "[@},]")
20198 re-search-forward("[@},]")
20199 (while ...)
20200 (let ...)
20201 texinfo-format-parse-args()
20202 (let ...)
20203 texinfo-format-xref()
20204 funcall(texinfo-format-xref)
20205 (if ...)
20206 (let ...)
20207 (if ...)
20208 (while ...)
20209 texinfo-format-scan()
20210 (save-excursion ...)
20211 (let ...)
20212 texinfo-format-region(103370 103631)
20213 * call-interactively(texinfo-format-region)
20214 ---------- Buffer: *Backtrace* ----------
20215 @end example
20216
20217 The backtrace is read from the bottom up.
20218 @code{texinfo-format-region} was called interactively; and it, in
20219 turn, called various functions, including @code{texinfo-format-scan},
20220 @code{texinfo-format-xref} and @code{texinfo-format-parse-args}.
20221 Inside the function @code{texinfo-format-parse-args}, the function
20222 @code{re-search-forward} was called; it was this function that could
20223 not find the missing right-hand brace.@refill
20224
20225 @xref{Lisp Debug, , Debugging XEmacs Lisp, xemacs, XEmacs User's Manual},
20226 for more information.@refill
20227 @end ignore
20228
20229 @node Debugging with TeX
20230 @comment node-name, next, previous, up
20231 @section Catching Errors with @TeX{} Formatting
20232 @cindex Catching errors with @TeX{} formatting
20233 @cindex Debugging with @TeX{} formatting
20234
20235 You can also catch mistakes when you format a file with @TeX{}.@refill
20236
20237 Usually, you will want to do this after you have run
20238 @code{texinfo-format-buffer} (or, better, @code{makeinfo-buffer}) on
20239 the same file, because @code{texinfo-format-buffer} sometimes displays
20240 error messages that make more sense than @TeX{}. (@xref{Debugging
20241 with Info}, for more information.)@refill
20242
20243 For example, @TeX{} was run on a Texinfo file, part of which is shown
20244 here:@refill
20245
20246 @example
20247 ---------- Buffer: texinfo.texi ----------
20248 name of the Texinfo file as an extension. The
20249 @@samp@{??@} are `wildcards' that cause the shell to
20250 substitute all the raw index files. (@@xref@{sorting
20251 indices, for more information about sorting
20252 indices.)@@refill
20253 ---------- Buffer: texinfo.texi ----------
20254 @end example
20255
20256 @noindent
20257 (The cross reference lacks a closing brace.)
20258 @TeX{} produced the following output, after which it stopped:@refill
20259
20260 @example
20261 ---------- Buffer: *tex-shell* ----------
20262 Runaway argument?
20263 @{sorting indices, for more information about sorting
20264 indices.) @@refill @@ETC.
20265 ! Paragraph ended before @@xref was complete.
20266 <to be read again>
20267 @@par
20268 l.27
20269
20270 ?
20271 ---------- Buffer: *tex-shell* ----------
20272 @end example
20273
20274 In this case, @TeX{} produced an accurate and
20275 understandable error message:
20276
20277 @example
20278 Paragraph ended before @@xref was complete.
20279 @end example
20280
20281 @noindent
20282 @samp{@@par} is an internal @TeX{} command of no relevance to Texinfo.
20283 @samp{l.27} means that @TeX{} detected the problem on line 27 of the
20284 Texinfo file. The @samp{?} is the prompt @TeX{} uses in this
20285 circumstance.@refill
20286
20287 Unfortunately, @TeX{} is not always so helpful, and sometimes you must
20288 truly be a Sherlock Holmes to discover what went wrong.@refill
20289
20290 In any case, if you run into a problem like this, you can do one of three
20291 things.@refill
20292
20293 @enumerate
20294 @item
20295 You can tell @TeX{} to continue running and ignore just this error by
20296 typing @key{RET} at the @samp{?} prompt.@refill
20297
20298 @item
20299 You can tell @TeX{} to continue running and to ignore all errors as best
20300 it can by typing @kbd{r @key{RET}} at the @samp{?} prompt.@refill
20301
20302 This is often the best thing to do. However, beware: the one error
20303 may produce a cascade of additional error messages as its consequences
20304 are felt through the rest of the file. To stop @TeX{} when it is
20305 producing such an avalanche of error messages, type @kbd{C-c} (or
20306 @kbd{C-c C-c}, if you are running a shell inside XEmacs).
20307
20308 @item
20309 You can tell @TeX{} to stop this run by typing @kbd{x @key{RET}}
20310 at the @samp{?} prompt.@refill
20311 @end enumerate
20312
20313 If you are running @TeX{} inside XEmacs, you need to switch to the shell
20314 buffer and line at which @TeX{} offers the @samp{?} prompt.
20315
20316 Sometimes @TeX{} will format a file without producing error messages even
20317 though there is a problem. This usually occurs if a command is not ended
20318 but @TeX{} is able to continue processing anyhow. For example, if you fail
20319 to end an itemized list with the @code{@@end itemize} command, @TeX{} will
20320 write a DVI file that you can print out. The only error message that
20321 @TeX{} will give you is the somewhat mysterious comment that@refill
20322
20323 @example
20324 (@@end occurred inside a group at level 1)
20325 @end example
20326
20327 @noindent
20328 However, if you print the DVI file, you will find that the text
20329 of the file that follows the itemized list is entirely indented as if
20330 it were part of the last item in the itemized list. The error message
20331 is the way @TeX{} says that it expected to find an @code{@@end}
20332 command somewhere in the file; but that it could not determine where
20333 it was needed.@refill
20334
20335 Another source of notoriously hard-to-find errors is a missing
20336 @code{@@end group} command. If you ever are stumped by
20337 incomprehensible errors, look for a missing @code{@@end group} command
20338 first.@refill
20339
20340 If the Texinfo file lacks header lines,
20341 @TeX{} may stop in the
20342 beginning of its run and display output that looks like the following.
20343 The @samp{*} indicates that @TeX{} is waiting for input.@refill
20344
20345 @example
20346 This is TeX, Version 3.14159 (Web2c 7.0)
20347 (test.texinfo [1])
20348 *
20349 @end example
20350
20351 @noindent
20352 In this case, simply type @kbd{\end @key{RET}} after the asterisk. Then
20353 write the header lines in the Texinfo file and run the @TeX{} command
20354 again. (Note the use of the backslash, @samp{\}. @TeX{} uses @samp{\}
20355 instead of @samp{@@}; and in this circumstance, you are working
20356 directly with @TeX{}, not with Texinfo.)@refill
20357
20358 @node Using texinfo-show-structure
20359 @comment node-name, next, previous, up
20360 @section Using @code{texinfo-show-structure}
20361 @cindex Showing the structure of a file
20362 @findex texinfo-show-structure
20363
20364 It is not always easy to keep track of the nodes, chapters, sections, and
20365 subsections of a Texinfo file. This is especially true if you are revising
20366 or adding to a Texinfo file that someone else has written.@refill
20367
20368 In XEmacs, in Texinfo mode, the @code{texinfo-show-structure}
20369 command lists all the lines that begin with the @@-commands that
20370 specify the structure: @code{@@chapter}, @code{@@section},
20371 @code{@@appendix}, and so on. With an argument (@w{@kbd{C-u}}
20372 as prefix argument, if interactive),
20373 the command also shows the @code{@@node} lines. The
20374 @code{texinfo-show-structure} command is bound to @kbd{C-c C-s} in
20375 Texinfo mode, by default.@refill
20376
20377 The lines are displayed in a buffer called the @samp{*Occur*} buffer,
20378 indented by hierarchical level. For example, here is a part of what was
20379 produced by running @code{texinfo-show-structure} on this manual:@refill
20380
20381 @example
20382 @group
20383 Lines matching "^@@\\(chapter \\|sect\\|subs\\|subh\\|
20384 unnum\\|major\\|chapheading \\|heading \\|appendix\\)"
20385 in buffer texinfo.texi.
20386 @dots{}
20387 4177:@@chapter Nodes
20388 4198: @@heading Two Paths
20389 4231: @@section Node and Menu Illustration
20390 4337: @@section The @@code@{@@@@node@} Command
20391 4393: @@subheading Choosing Node and Pointer Names
20392 4417: @@subsection How to Write an @@code@{@@@@node@} Line
20393 4469: @@subsection @@code@{@@@@node@} Line Tips
20394 @dots{}
20395 @end group
20396 @end example
20397
20398 This says that lines 4337, 4393, and 4417 of @file{texinfo.texi} begin
20399 with the @code{@@section}, @code{@@subheading}, and @code{@@subsection}
20400 commands respectively. If you move your cursor into the @samp{*Occur*}
20401 window, you can position the cursor over one of the lines and use the
20402 @kbd{C-c C-c} command (@code{occur-mode-goto-occurrence}), to jump to
20403 the corresponding spot in the Texinfo file. @xref{Other Repeating
20404 Search, , Using Occur, xemacs, XEmacs User's Manual}, for more
20405 information about @code{occur-mode-goto-occurrence}.@refill
20406
20407 The first line in the @samp{*Occur*} window describes the @dfn{regular
20408 expression} specified by @var{texinfo-heading-pattern}. This regular
20409 expression is the pattern that @code{texinfo-show-structure} looks for.
20410 @xref{Regexps, , Using Regular Expressions, xemacs, XEmacs User's Manual},
20411 for more information.@refill
20412
20413 When you invoke the @code{texinfo-show-structure} command, XEmacs will
20414 display the structure of the whole buffer. If you want to see the
20415 structure of just a part of the buffer, of one chapter, for example,
20416 use the @kbd{C-x n n} (@code{narrow-to-region}) command to mark the
20417 region. (@xref{Narrowing, , , xemacs, XEmacs User's Manual}.) This is
20418 how the example used above was generated. (To see the whole buffer
20419 again, use @kbd{C-x n w} (@code{widen}).)@refill
20420
20421 If you call @code{texinfo-show-structure} with a prefix argument by
20422 typing @w{@kbd{C-u C-c C-s}}, it will list lines beginning with
20423 @code{@@node} as well as the lines beginning with the @@-sign commands
20424 for @code{@@chapter}, @code{@@section}, and the like.@refill
20425
20426 You can remind yourself of the structure of a Texinfo file by looking at
20427 the list in the @samp{*Occur*} window; and if you have mis-named a node
20428 or left out a section, you can correct the mistake.@refill
20429
20430 @node Using occur
20431 @comment node-name, next, previous, up
20432 @section Using @code{occur}
20433 @cindex Occurrences, listing with @code{@@occur}
20434 @findex occur
20435
20436 Sometimes the @code{texinfo-show-structure} command produces too much
20437 information. Perhaps you want to remind yourself of the overall structure
20438 of a Texinfo file, and are overwhelmed by the detailed list produced by
20439 @code{texinfo-show-structure}. In this case, you can use the @code{occur}
20440 command directly. To do this, type@refill
20441
20442 @example
20443 @kbd{M-x occur}
20444 @end example
20445
20446 @noindent
20447 and then, when prompted, type a @dfn{regexp}, a regular expression for
20448 the pattern you want to match. (@xref{Regexps, , Regular Expressions,
20449 xemacs, XEmacs User's Manual}.) The @code{occur} command works from the
20450 current location of the cursor in the buffer to the end of the buffer.
20451 If you want to run @code{occur} on the whole buffer, place the cursor at
20452 the beginning of the buffer.@refill
20453
20454 For example, to see all the lines that contain the word
20455 @samp{@@chapter} in them, just type @samp{@@chapter}. This will
20456 produce a list of the chapters. It will also list all the sentences
20457 with @samp{@@chapter} in the middle of the line.@refill
20458
20459 If you want to see only those lines that start with the word
20460 @samp{@@chapter}, type @samp{^@@chapter} when prompted by
20461 @code{occur}. If you want to see all the lines that end with a word
20462 or phrase, end the last word with a @samp{$}; for example,
20463 @samp{catching mistakes$}. This can be helpful when you want to see
20464 all the nodes that are part of the same chapter or section and
20465 therefore have the same `Up' pointer.@refill
20466
20467 @xref{Other Repeating Search, , Using Occur, xemacs, XEmacs User's Manual},
20468 for more information.@refill
20469
20470 @node Running Info-Validate
20471 @comment node-name, next, previous, up
20472 @section Finding Badly Referenced Nodes
20473 @findex Info-validate
20474 @cindex Nodes, checking for badly referenced
20475 @cindex Checking for badly referenced nodes
20476 @cindex Looking for badly referenced nodes
20477 @cindex Finding badly referenced nodes
20478 @cindex Badly referenced nodes
20479
20480 You can use the @code{Info-validate} command to check whether any of
20481 the `Next', `Previous', `Up' or other node pointers fail to point to a
20482 node. This command checks that every node pointer points to an
20483 existing node. The @code{Info-validate} command works only on Info
20484 files, not on Texinfo files.@refill
20485
20486 The @code{makeinfo} program validates pointers automatically, so you
20487 do not need to use the @code{Info-validate} command if you are using
20488 @code{makeinfo}. You only may need to use @code{Info-validate} if you
20489 are unable to run @code{makeinfo} and instead must create an Info file
20490 using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
20491 if you write an Info file from scratch.@refill
20492
20493 @menu
20494 * Using Info-validate:: How to run @code{Info-validate}.
20495 * Unsplit:: How to create an unsplit file.
20496 * Tagifying:: How to tagify a file.
20497 * Splitting:: How to split a file manually.
20498 @end menu
20499
20500 @node Using Info-validate
20501 @subsection Running @code{Info-validate}
20502 @cindex Running @code{Info-validate}
20503 @cindex Info validating a large file
20504 @cindex Validating a large file
20505
20506 To use @code{Info-validate}, visit the Info file you wish to check and
20507 type:@refill
20508
20509 @example
20510 M-x Info-validate
20511 @end example
20512
20513 @noindent
20514 Note that the @code{Info-validate} command requires an upper case
20515 `I'. You may also need to create a tag table before running
20516 @code{Info-validate}. @xref{Tagifying}.
20517
20518 If your file is valid, you will receive a message that says ``File appears
20519 valid''. However, if you have a pointer that does not point to a node,
20520 error messages will be displayed in a buffer called @samp{*problems in
20521 info file*}.@refill
20522
20523 For example, @code{Info-validate} was run on a test file that contained
20524 only the first node of this manual. One of the messages said:@refill
20525
20526 @example
20527 In node "Overview", invalid Next: Texinfo Mode
20528 @end example
20529
20530 @noindent
20531 This meant that the node called @samp{Overview} had a `Next' pointer that
20532 did not point to anything (which was true in this case, since the test file
20533 had only one node in it).@refill
20534
20535 Now suppose we add a node named @samp{Texinfo Mode} to our test case
20536 but we do not specify a `Previous' for this node. Then we will get
20537 the following error message:@refill
20538
20539 @example
20540 In node "Texinfo Mode", should have Previous: Overview
20541 @end example
20542
20543 @noindent
20544 This is because every `Next' pointer should be matched by a
20545 `Previous' (in the node where the `Next' points) which points back.@refill
20546
20547 @code{Info-validate} also checks that all menu entries and cross references
20548 point to actual nodes.@refill
20549
20550 @code{Info-validate} requires a tag table and does not work with files
20551 that have been split. (The @code{texinfo-format-buffer} command
20552 automatically splits large files.) In order to use @code{Info-validate}
20553 on a large file, you must run @code{texinfo-format-buffer} with an
20554 argument so that it does not split the Info file; and you must create a
20555 tag table for the unsplit file.
20556
20557 @node Unsplit
20558 @comment node-name, next, previous, up
20559 @subsection Creating an Unsplit File
20560 @cindex Creating an unsplit file
20561 @cindex Unsplit file creation
20562
20563 You can run @code{Info-validate} only on a single Info file that has a
20564 tag table. The command will not work on the indirect subfiles that
20565 are generated when a master file is split. If you have a large file
20566 (longer than 300,000 bytes or so), you need to run the
20567 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command in such
20568 a way that it does not create indirect subfiles. You will also need
20569 to create a tag table for the Info file. After you have done this,
20570 you can run @code{Info-validate} and look for badly referenced
20571 nodes.@refill
20572
20573 The first step is to create an unsplit Info file. To prevent
20574 @code{texinfo-format-buffer} from splitting a Texinfo file into
20575 smaller Info files, give a prefix to the @kbd{M-x
20576 texinfo-format-buffer} command:@refill
20577
20578 @example
20579 C-u M-x texinfo-format-buffer
20580 @end example
20581
20582 @noindent
20583 or else
20584
20585 @example
20586 C-u C-c C-e C-b
20587 @end example
20588
20589 @noindent
20590 When you do this, Texinfo will not split the file and will not create
20591 a tag table for it. @refill
20592 @cindex Making a tag table manually
20593 @cindex Tag table, making manually
20594
20595 @node Tagifying
20596 @subsection Tagifying a File
20597
20598 After creating an unsplit Info file, you must create a tag table for
20599 it. Visit the Info file you wish to tagify and type:@refill
20600
20601 @example
20602 M-x Info-tagify
20603 @end example
20604
20605 @noindent
20606 (Note the upper case @samp{I} in @code{Info-tagify}.) This creates an
20607 Info file with a tag table that you can validate.@refill
20608
20609 The third step is to validate the Info file:@refill
20610
20611 @example
20612 M-x Info-validate
20613 @end example
20614
20615 @noindent
20616 (Note the upper case @samp{I} in @code{Info-validate}.)
20617 In brief, the steps are:@refill
20618
20619 @example
20620 @group
20621 C-u M-x texinfo-format-buffer
20622 M-x Info-tagify
20623 M-x Info-validate
20624 @end group
20625 @end example
20626
20627 After you have validated the node structure, you can rerun
20628 @code{texinfo-format-buffer} in the normal way so it will construct a
20629 tag table and split the file automatically, or you can make the tag
20630 table and split the file manually.@refill
20631
20632 @node Splitting
20633 @comment node-name, next, previous, up
20634 @subsection Splitting a File Manually
20635 @cindex Splitting an Info file manually
20636 @cindex Info file, splitting manually
20637
20638 You should split a large file or else let the
20639 @code{texinfo-format-buffer} or @code{makeinfo-buffer} command do it
20640 for you automatically. (Generally you will let one of the formatting
20641 commands do this job for you. @xref{Creating an Info File}.)@refill
20642
20643 The split-off files are called the indirect subfiles.@refill
20644
20645 Info files are split to save memory. With smaller files, XEmacs does not
20646 have make such a large buffer to hold the information.@refill
20647
20648 If an Info file has more than 30 nodes, you should also make a tag
20649 table for it. @xref{Using Info-validate}, for information
20650 about creating a tag table. (Again, tag tables are usually created
20651 automatically by the formatting command; you only need to create a tag
20652 table yourself if you are doing the job manually. Most likely, you
20653 will do this for a large, unsplit file on which you have run
20654 @code{Info-validate}.)@refill
20655
20656 @c Info-split is autoloaded in `loaddefs.el' in Emacs 18.51
20657 @ignore
20658 Before running @code{Info-split}, you need to load the @code{info} library
20659 into XEmacs by giving the command @kbd{M-x load-library @key{RET} info
20660 @key{RET}}.
20661 @end ignore
20662
20663 Visit the Info file you wish to tagify and split and type the two
20664 commands:@refill
20665
20666 @example
20667 M-x Info-tagify
20668 M-x Info-split
20669 @end example
20670
20671 @noindent
20672 (Note that the @samp{I} in @samp{Info} is upper case.)@refill
20673
20674 When you use the @code{Info-split} command, the buffer is modified into a
20675 (small) Info file which lists the indirect subfiles. This file should be
20676 saved in place of the original visited file. The indirect subfiles are
20677 written in the same directory the original file is in, with names generated
20678 by appending @samp{-} and a number to the original file name.@refill
20679
20680 The primary file still functions as an Info file, but it contains just
20681 the tag table and a directory of subfiles.@refill
20682
20683
20684 @ignore
20685 The simple description in the command summary seems sufficient to me
20686 these days, so ignore this appendix. --karl, 13mar04.
20687
20688 @node Refilling Paragraphs
20689 @appendix Refilling Paragraphs
20690 @cindex Refilling paragraphs
20691 @cindex Filling paragraphs
20692 @cindex Paragraphs, filling
20693 @findex refill
20694
20695 The @code{@@refill} command refills and, optionally, indents the first
20696 line of a paragraph.@footnote{Perhaps the command should have been
20697 called the @code{@@refillandindent} command, but @code{@@refill} is
20698 shorter and the name was chosen before indenting was possible.} The
20699 @code{@@refill} command is no longer important, but we describe it here
20700 because you once needed it. You will see it in many old Texinfo
20701 files.@refill
20702
20703 Without refilling, paragraphs containing long @@-constructs may look
20704 bad after formatting because the formatter removes @@-commands and
20705 shortens some lines more than others. In the past, neither the
20706 @code{texinfo-format-region} command nor the
20707 @code{texinfo-format-buffer} command refilled paragraphs
20708 automatically. The @code{@@refill} command had to be written at the
20709 end of every paragraph to cause these formatters to fill them. (Both
20710 @TeX{} and @code{makeinfo} have always refilled paragraphs
20711 automatically.) Now, all the Info formatters automatically fill and
20712 indent those paragraphs that need to be filled and indented.@refill
20713
20714 The @code{@@refill} command causes @code{texinfo-format-region} and
20715 @code{texinfo-format-buffer} to refill a paragraph in the Info file
20716 @emph{after} all the other processing has been done. For this reason,
20717 you can not use @code{@@refill} with a paragraph containing either
20718 @code{@@*} or @code{@@w@{ @dots{} @}} since the refilling action will
20719 override those two commands.@refill
20720
20721 The @code{texinfo-format-region} and @code{texinfo-format-buffer}
20722 commands now automatically append @code{@@refill} to the end of each
20723 paragraph that should be filled. They do not append @code{@@refill} to
20724 the ends of paragraphs that contain @code{@@*} or @w{@code{@@w@{ @dots{}@}}}
20725 and therefore do not refill or indent them.@refill
20726
20727 @end ignore
20728
20729
20730 @c These are no longer ``new'', and the explanations
20731 @c are all given elsewhere anyway, I think. --karl, 25apr97.
20732 @c So ignore the entire appendix.
20733 @ignore
20734 @c node New Features, Command and Variable Index, Obtaining TeX, Top
20735 @c appendix Second Edition Features
20736
20737 @tex
20738 % Widen the space for the first column so three control-character
20739 % strings fit in the first column. Switched back to default .8in
20740 % value at end of chapter.
20741 \global\tableindent=1.0in
20742 @end tex
20743
20744 The second edition of the Texinfo manual describes more than 20 new
20745 Texinfo mode commands and more than 50 previously undocumented Texinfo
20746 @@-commands. This edition is more than twice the length of the first
20747 edition.@refill
20748
20749 Here is a brief description of the new commands.@refill
20750
20751 @c menu
20752 * New Texinfo Mode Commands:: The updating commands are especially useful.
20753 * New Commands:: Many newly described @@-commands.
20754 @c end menu
20755
20756 @c node New Texinfo Mode Commands, New Commands, Obtaining TeX, Obtaining TeX
20757 @c appendixsec New Texinfo Mode Commands
20758
20759 Texinfo mode provides commands and features especially designed for
20760 working with Texinfo files. More than 20 new commands have been
20761 added, including commands for automatically creating and updating
20762 both nodes and menus. This is a tedious task when done by hand.@refill
20763
20764 The keybindings are intended to be somewhat mnemonic.@refill
20765
20766 @c subheading Update all nodes and menus
20767
20768 The @code{texinfo-master-menu} command is the primary command:
20769
20770 @table @kbd
20771 @item C-c C-u m
20772 @itemx M-x texinfo-master-menu
20773 Create or update a master menu.
20774 With @kbd{C-u} as a prefix argument,
20775 first create or update all nodes
20776 and regular menus.
20777 @end table
20778
20779 @c subheading Update Pointers
20780
20781 @noindent
20782 Create or update `Next', `Previous', and `Up' node pointers.@refill
20783
20784 @noindent
20785 @xref{Updating Nodes and Menus}.
20786
20787 @table @kbd
20788 @item C-c C-u C-n
20789 @itemx M-x texinfo-update-node
20790 Update a node.
20791
20792 @item C-c C-u C-e
20793 @itemx M-x texinfo-every-node-update
20794 Update every node in the buffer.
20795 @end table
20796
20797 @c subheading Update Menus
20798
20799 @noindent
20800 Create or update menus.@refill
20801
20802 @noindent
20803 @xref{Updating Nodes and Menus}.
20804
20805 @table @kbd
20806 @item C-c C-u C-m
20807 @itemx M-x texinfo-make-menu
20808 Make or update a menu.
20809
20810 @item C-c C-u C-a
20811 @itemx M-x texinfo-all-menus-update
20812 Make or update all the menus in a buffer.
20813 With @kbd{C-u} as a prefix argument,
20814 first update all the nodes.
20815 @end table
20816
20817 @c subheading Insert Title as Description
20818
20819 @noindent
20820 Insert a node's chapter or section title in the space for the
20821 description in a menu entry line; position point so you can edit the
20822 insert. (This command works somewhat differently than the other
20823 insertion commands, which insert only a predefined string.)@refill
20824
20825 @noindent
20826 @xref{Inserting, Inserting Frequently Used Commands}.
20827
20828 @table @kbd
20829 @item C-c C-c C-d
20830 Insert title.
20831 @end table
20832
20833 @c subheading Format for Info
20834
20835 @noindent
20836 Provide keybindings both for the Info formatting commands that are
20837 written in XEmacs Lisp and for @code{makeinfo} that is written in
20838 C.@refill
20839
20840 @noindent
20841 @xref{Info Formatting}.
20842
20843 @noindent
20844 Use the XEmacs lisp @code{texinfo-format@dots{}} commands:
20845
20846 @table @kbd
20847 @item C-c C-e C-r
20848 Format the region.
20849
20850 @item C-c C-e C-b
20851 Format the buffer.
20852 @end table
20853
20854 @noindent
20855 Use @code{makeinfo}:
20856
20857 @table @kbd
20858 @item C-c C-m C-r
20859 Format the region.
20860
20861 @item C-c C-m C-b
20862 Format the buffer.
20863
20864 @item C-c C-m C-l
20865 Recenter the @code{makeinfo} output buffer.
20866
20867 @item C-c C-m C-k
20868 Kill the @code{makeinfo} formatting job.
20869 @end table
20870
20871 @c subheading Typeset and Print
20872
20873 @noindent
20874 Typeset and print Texinfo documents from within XEmacs.
20875
20876 @noindent
20877 @xref{Printing}.
20878
20879 @table @kbd
20880 @item C-c C-t C-b
20881 Run @code{texi2dvi} on the buffer.
20882
20883 @item C-c C-t C-r
20884 Run @TeX{} on the region.
20885
20886 @item C-c C-t C-i
20887 Run @code{texindex}.
20888
20889 @item C-c C-t C-p
20890 Print the DVI file.
20891
20892 @item C-c C-t C-q
20893 Show the print queue.
20894
20895 @item C-c C-t C-d
20896 Delete a job from the print queue.
20897
20898 @item C-c C-t C-k
20899 Kill the current @TeX{} formatting job.
20900
20901 @item C-c C-t C-x
20902 Quit a currently stopped @TeX{} formatting job.
20903
20904 @item C-c C-t C-l
20905 Recenter the output buffer.
20906 @end table
20907
20908 @c subheading Other Updating Commands
20909
20910 @noindent
20911 The ``other updating commands'' do not have standard keybindings because
20912 they are used less frequently.@refill
20913
20914 @noindent
20915 @xref{Other Updating Commands}.
20916
20917 @table @kbd
20918 @item M-x texinfo-insert-node-lines
20919 Insert missing @code{@@node} lines using
20920 section titles as node names.
20921
20922 @item M-x texinfo-multiple-files-update
20923 Update a multi-file document.
20924 With a numeric prefix, such as @kbd{C-u 8},
20925 update @strong{every} pointer and
20926 menu in @strong{all} the files and
20927 then insert a master menu.
20928
20929 @item M-x texinfo-indent-menu-description
20930 Indent descriptions in menus.
20931
20932 @item M-x texinfo-sequential-node-update
20933 Insert node pointers in strict sequence.
20934 @end table
20935
20936 @c no.de New Commands, , New Texinfo Mode Commands, Obtaining TeX
20937 @c appendix.sec New Texinfo @@-Commands
20938
20939 The second edition of the Texinfo manual describes more than 50
20940 commands that were not described in the first edition. A third or so
20941 of these commands existed in Texinfo but were not documented in the
20942 manual; the others are new. Here is a listing, with brief
20943 descriptions of them:@refill
20944
20945 @c subheading Indexing
20946
20947 @noindent
20948 Create your own index, and merge indices.@refill
20949
20950 @noindent
20951 @xref{Indices}.
20952
20953 @table @kbd
20954 @item @@defindex @var{index-name}
20955 Define a new index and its indexing command.
20956 See also the @code{@@defcodeindex} command.
20957
20958 @c written verbosely to avoid overfull hbox
20959 @item @@synindex @var{from-index} @var{into-index}
20960 Merge the @var{from-index} index into the @var{into-index} index.
20961 See also the @code{@@syncodeindex} command.
20962 @end table
20963
20964 @c subheading Definitions
20965
20966 @noindent
20967 Describe functions, variables, macros,
20968 commands, user options, special forms, and other such artifacts in a
20969 uniform format.@refill
20970
20971 @noindent
20972 @xref{Definition Commands}.
20973
20974 @table @kbd
20975 @item @@deffn @var{category} @var{name} @var{arguments}@dots{}
20976 Format a description for functions, interactive
20977 commands, and similar entities.
20978
20979 @item @@defvr, @@defop, @dots{}
20980 15 other related commands.
20981 @end table
20982
20983 @c subheading Glyphs
20984
20985 @noindent
20986 Indicate the results of evaluation, expansion,
20987 printed output, an error message, equivalence of expressions, and the
20988 location of point.@refill
20989
20990 @noindent
20991 @xref{Glyphs}.
20992
20993 @table @kbd
20994 @item @@equiv@{@}
20995 @itemx @equiv{}
20996 Equivalence:
20997
20998 @item @@error@{@}
20999 @itemx @error{}
21000 Error message
21001
21002 @item @@expansion@{@}
21003 @itemx @expansion{}
21004 Macro expansion
21005
21006 @item @@point@{@}
21007 @itemx @point{}
21008 Position of point
21009
21010 @item @@print@{@}
21011 @itemx @print{}
21012 Printed output
21013
21014 @item @@result@{@}
21015 @itemx @result{}
21016 Result of an expression
21017 @end table
21018
21019 @c subheading Page Headings
21020
21021 @noindent
21022 Customize page headings.
21023
21024 @noindent
21025 @xref{Headings}.
21026
21027 @table @kbd
21028 @item @@headings @var{on-off-single-double}
21029 Headings on or off, single, or double-sided.
21030
21031 @item @@evenfooting [@var{left}] @@| [@var{center}] @@| [@var{right}]
21032 Footings for even-numbered (left-hand) pages.
21033
21034 @item @@evenheading, @@everyheading, @@oddheading, @dots{}
21035 Five other related commands.
21036
21037 @item @@thischapter
21038 Insert name of chapter and chapter number.
21039
21040 @item @@thischaptername, @@thisfile, @@thistitle, @@thispage
21041 Related commands.
21042 @end table
21043
21044 @c subheading Formatting
21045
21046 @noindent
21047 Format blocks of text.
21048
21049 @noindent
21050 @xref{Quotations and Examples}, and@*
21051 @ref{Lists and Tables, , Making Lists and Tables}.
21052
21053 @table @kbd
21054 @item @@cartouche
21055 Draw rounded box surrounding text (no effect in Info).
21056
21057 @item @@enumerate @var{optional-arg}
21058 Enumerate a list with letters or numbers.
21059
21060 @item @@exdent @var{line-of-text}
21061 Remove indentation.
21062
21063 @item @@flushleft
21064 Left justify.
21065
21066 @item @@flushright
21067 Right justify.
21068
21069 @item @@format
21070 Do not narrow nor change font.
21071
21072 @item @@ftable @var{formatting-command}
21073 @itemx @@vtable @var{formatting-command}
21074 Two-column table with indexing.
21075
21076 @item @@lisp
21077 For an example of Lisp code.
21078
21079 @item @@smallexample
21080 @itemx @@smalllisp
21081 Like @@table and @@lisp, but for (originally) @@smallbook.
21082 @end table
21083
21084 @c subheading Conditionals
21085
21086 @noindent
21087 Conditionally format text.
21088
21089 @noindent
21090 @xref{set clear value, , @code{@@set} @code{@@clear} @code{@@value}}.@refill
21091
21092 @table @kbd
21093 @item @@set @var{flag} [@var{string}]
21094 Set a flag. Optionally, set value
21095 of @var{flag} to @var{string}.
21096
21097 @item @@clear @var{flag}
21098 Clear a flag.
21099
21100 @item @@value@{@var{flag}@}
21101 Replace with value to which @var{flag} is set.
21102
21103 @item @@ifset @var{flag}
21104 Format, if @var{flag} is set.
21105
21106 @item @@ifclear @var{flag}
21107 Ignore, if @var{flag} is set.
21108 @end table
21109
21110 @c subheading @@heading series for Titles
21111
21112 @noindent
21113 Produce unnumbered headings that do not appear in a table of contents.
21114
21115 @noindent
21116 @xref{Structuring}.
21117
21118 @table @kbd
21119 @item @@heading @var{title}
21120 Unnumbered section-like heading not listed
21121 in the table of contents of a printed manual.
21122
21123 @item @@chapheading, @@majorheading, @@c subheading, @@subsubheading
21124 Related commands.
21125 @end table
21126
21127 @need 1000
21128 @c subheading Font commands
21129
21130 @need 1000
21131 @noindent
21132 @xref{Smallcaps}, and @*
21133 @ref{Fonts}.
21134
21135 @table @kbd
21136 @item @@r@{@var{text}@}
21137 Print in roman font.
21138
21139 @item @@sc@{@var{text}@}
21140 Print in @sc{small caps} font.
21141 @end table
21142
21143 @c subheading Miscellaneous
21144
21145 @noindent
21146 See @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author} Commands},@*
21147 see @ref{Customized Highlighting},@*
21148 see @ref{Overfull hboxes},@*
21149 see @ref{Footnotes},@*
21150 see @ref{dmn, , Format a Dimension},@*
21151 see @ref{Raise/lower sections, , @code{@@raisesections} and @code{@@lowersections}},@*
21152 see @ref{math, , @code{@@math} - Inserting Mathematical Expressions}.@*
21153 see @ref{minus, , Inserting a Minus Sign},@*
21154 see @ref{paragraphindent, , Paragraph Indenting},@*
21155 see @ref{Cross Reference Commands},@*
21156 see @ref{title subtitle author, , @code{@@title} @code{@@subtitle} and @code{@@author}}, and@*
21157 see @ref{Custom Headings, , How to Make Your Own Headings}.
21158
21159 @table @kbd
21160 @item @@author @var{author}
21161 Typeset author's name.
21162
21163 @c @item @@definfoenclose @var{new-command}, @var{before}, @var{after},
21164 @c Define a highlighting command for Info. (Info only.)
21165
21166 @item @@finalout
21167 Produce cleaner printed output.
21168
21169 @item @@footnotestyle @var{end-or-separate}
21170 Specify footnote style, either @samp{end} or @samp{separate}.
21171 @xref{Footnote Styles}.
21172
21173 @item @@dmn@{@var{dimension}@}
21174 Format a dimension.
21175
21176 @item @@global@@let@var{new-cmd}=@var{existing-cmd}
21177 Define a highlighting command for @TeX{}. (@TeX{} only.)
21178
21179 @item @@lowersections
21180 Reduce hierarchical level of sectioning commands.
21181
21182 @item @@math@{@var{mathematical-expression}@}
21183 Format a mathematical expression.
21184
21185 @item @@minus@{@}
21186 Generate a minus sign.
21187
21188 @item @@paragraphindent @var{asis-or-number}
21189 Specify paragraph indentation.
21190
21191 @item @@raisesections
21192 Raise hierarchical level of sectioning commands.
21193
21194 @item @@ref@{@var{node-name}, @r{[}@var{entry}@r{]}, @r{[}@var{topic-or-title}@r{]}, @r{[}@var{info-file}@r{]}, @r{[}@var{manual}@r{]}@}
21195 Make a reference. In the printed manual, the
21196 reference does not start with the word `see'.
21197
21198 @item @@title @var{title}
21199 Typeset @var{title} in the alternative
21200 title page format.
21201
21202 @item @@subtitle @var{subtitle}
21203 Typeset @var{subtitle} in the alternative
21204 title page format.
21205
21206 @item @@today@{@}
21207 Insert the current date.
21208 @end table
21209 @tex
21210 % Switch width of first column of tables back to default value
21211 \global\tableindent=.8in
21212 @end tex
21213 @end ignore
21214
21215
21216 @node GNU Free Documentation License
21217 @appendix GNU Free Documentation License
21218
21219 @include fdl.texi
21220
21221
21222 @node Command and Variable Index
21223 @unnumbered Command and Variable Index
21224
21225 This is an alphabetical list of all the @@-commands, assorted XEmacs Lisp
21226 functions, and several variables. To make the list easier to use, the
21227 commands are listed without their preceding @samp{@@}.@refill
21228
21229 @printindex fn
21230
21231
21232 @node General Index
21233 @unnumbered General Index
21234
21235 @printindex cp
21236
21237
21238 @bye